How to document Python packages using Sphinx

Question

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 sphinx-quickstart firing. In conf.py I have uncommented sys.path.insert(0, os.path.abspath('.')) , And I have extensions = ['sphinx.ext.autodoc'] .

My index.rst :

 .. 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 documentation! ================================== Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 

In all __init__.py , I have a docstring, and this applies to the foo.py and bar.py . However, when I run make html in the project, I do not see any of the documents.

Answer 1

Here is the diagram:

1. Document your package using documentation lines in the sources.
2. Use sphinx-quickstart to create a Sphinx project.

3. Run sphinx-apidoc to generate .rst sources configured for use with autodoc . More info 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-execute this command several times.

4. Collect documentation using sphinx-build .

Notes:

• Sphinx requires .rst files with directives like automodule or autoclass to generate API documentation. It does not automatically extract anything from Python sources without these files. This is different from how tools like Epydoc or Doxygen work. The differences are more detailed: what is the relationship between documents and the sphinx? ,

• After running sphinx-apidoc, you may need to configure sys.path in conf.py for autodoc to find your modules.

• To avoid strange errors, as in these matters, how can I resolve the conflict between OptionParser and sphinx-build in a large project? Is OptionParser in conflict with sphinx? , make sure the code is structured correctly using if __name__ == "__main__": if necessary.