How to document Python packages using Sphinx

Dror picture Dror · Aug 28, 2014 · Viewed 10k times · Source

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.

Answer

mzjn picture mzjn · Aug 28, 2014

Here is an outline:

  1. Document your package using docstrings in the sources.
  2. Use sphinx-quickstart to create a Sphinx project.
  3. 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.

  4. Build the documentation using sphinx-build.

Notes: