CODEWITHSUNDEEP
pythonpython-sphinx
Arne
Arne

Reputation: 20237

Generate sphinx docu from docstrings not working

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, i.e. 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.

Upvotes: 5

Views: 10261

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15065

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.

Upvotes: 5

Related Questions