从文档字符串生成狮身人面像文档

Question

I have a project with the following structure (which I would like to keep):

my_project
├── build  # here is where sphinx should dump into
├── requirements.txt
├── make.bat
├── Makefile
├── ...  # more config files
├── doc  # this is where I want sphinx files to live
│   ├── conf.py
│   └── index.rst
├── src
│   └── my_project
│       ├── __init__.py
│       ├── module_1
│       │   ├── __init__.py
│       │   └── ...
│       └── util
│           ├── __init__.py
│           └── ...
└── tests
    ├── module_1
    │   ├── __init__.py
    │   └── ...  # testing module 1
    └── util
        ├── __init__.py
        └── ...  # testing util stuff

I recreated it on github , which can be used to recreate the results by executing my_setup.sh within.

I want to build the documentation from docstrings. I used sphinx's quickstart to generate necessary config, but when I call make hmtl , the resulting docu doesn't include any docstrings from my source code, ie everything in my_project/src/my_project . Sphinx's documenation is a bit overwhelming, given that I feel that I am trying to set up something very basic.

Relevant info from config files (please tell me if I forgot something important):

Makefile

SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SPHINXPROJ    = my_project
SOURCEDIR     = doc
BUILDDIR      = build
...

make.bat

set SOURCEDIR=doc
set BUILDDIR=build
set SPHINXPROJ=my_project
...

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('../src/my_project'))
...
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
]
...

---

I tried this as well, but it first put a bunch of build files into doc that I'd rather not have there and it also didn't find any of the modules (fixed by omitting the -F parameter):

$ sphinx-apidoc -F -o doc/ src/my_project/
$ cd doc
$ make html
Running Sphinx v1.7.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] my_project.util                                                                                                                                                                                  
WARNING: autodoc: failed to import module 'my_project'; the following exception was raised:
No module named 'my_project'
WARNING: autodoc: failed to import module 'my_project.util.test_file'; the following exception was raised:
No module named 'my_project'
WARNING: autodoc: failed to import module 'my_project.util'; the following exception was raised:
No module named 'my_project'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/arne/workspace/git/my_project/doc/my_project.rst: WARNING: document isn\'t included in any toctree
done
preparing documents... done
writing output... [100%] my_project.util                                                                                                                                                                                   
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 4 warnings.

Answer 1

There are a couple of issues with your MCVE.

1. rST source files must not reside in the output directory build , and should be in the docs source directory docs . You should have done this instead: sphinx-apidoc -o docs src/my_project .

2. As @mzjn mentioned, you need to uncomment and add some lines to your conf.py to resolve the WARNING: autodoc: failed to import module errors.

    # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # import os import sys # sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../src/')) 

After those two changes, I was able to successfully build your docs with its API.