I am trying to document a package in Python. At the moment I have the following directory structure:
.
└── project
├── _build
│ ├── doctrees
│ └── html
│ ├── _sources
│ └── _static
├── conf.py
├── index.rst
├── __init__.py
├── make.bat
├── Makefile
├── mod1
│ ├── foo.py
│ └── __init__.py
├── mod2
│ ├── bar.py
│ └── __init__.py
├── _static
└── _templates
This tree is the result of the firing of sphinx-quickstart
. In conf.py
I uncommented sys.path.insert(0, os.path.abspath('.'))
and I have extensions = ['sphinx.ext.autodoc']
.
My index.rst
is:
.. FooBar documentation master file, created by
sphinx-quickstart on Thu Aug 28 14:22:57 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to FooBar's documentation!
==================================
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
In all the __init__.py
's I have a docstring and same goes to the modules foo.py
and bar.py
. However, when running make html
in the project I don't see any of the docstings.
Here is an outline:
Run sphinx-apidoc to generate .rst sources set up for use with autodoc. More information here.
Using this command with the -F
flag also creates a complete Sphinx project. If your API changes a lot, you may need to re-run this command several times.
Notes:
Sphinx requires .rst files with directives like automodule
or autoclass
in order to generate API documentation. It does not automatically extract anything from the Python sources without these files. This is different from how tools like Epydoc or Doxygen work. The differences are elaborated a bit more here: What is the relationship between docutils and Sphinx?.
After you have run sphinx-apidoc, it may be necessary to adjust sys.path
in conf.py for autodoc to find your modules.
In order to avoid strange errors like in these questions, How should I solve the conflict of OptionParser and sphinx-build in a large project?, Is OptionParser in conflict with sphinx?, make sure that the code is properly structured, using if __name__ == "__main__":
guards when needed.