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 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.

You have a single top level index.rst file but nothing else. That is not enough. You need to run [sphinx-apidoc](http://sphinx-doc.org/man/sphinx-apidoc.html) to generate the needed .rst sources (or create them "by hand"). — mzjn, Aug 28 '14 at 13:10
Sphinx requires .rst files with directives like `automodule` or `autoclass` in order to generate API documentation. It does not extract from the sources without that. Maybe you expected Sphinx to work like Epydoc or Doxygen, but it does not. See also these answers: http://stackoverflow.com/a/2441159/407651, http://stackoverflow.com/a/6109098/407651. — mzjn, Aug 28 '14 at 13:28
Let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/60179/discussion-between-dror-and-mzjn). — Dror, Aug 28 '14 at 14:28
Just wrote a complete working example with PyCharm, it can be used for inspiration. https://stackoverflow.com/a/46362065/1980180 — Ferhat S. R., Sep 25 '17 at 10:09

mzjn · Accepted Answer · 2019-01-31T10:57:07.710

10

Here is an outline:

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

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.

edited Jan 31 '19 at 10:57

answered Aug 28 '14 at 18:51

mzjn

48,958
13
128
248

1

Where should I run `sphinx-apidoc`? What do do with generated `.rst` files? Where to put them? How is using `-F` different from `spinx-quickstart`? – minerals Dec 31 '15 at 08:29
@minerals. *Where should I run sphinx-apidoc?* What do you mean by "where"? What is the problem? *What do do with generated .rst files? Where to put them?* You put them wherever is convenient. And then you run `sphinx-build` on them. – mzjn Dec 31 '15 at 09:26
1

@minerals. *How is using -F different from spinx-quickstart?* If you run `sphinx-apidoc -F`, you in effect run `sphinx-quickstart` and `sphinx-apidoc` in one go. That's just another way of doing it. – mzjn Dec 31 '15 at 09:26
@minerals. Regarding `sphinx-apidoc`: I linked to http://sphinx-doc.org/man/sphinx-apidoc.html in my answer. Is there something that is unclear on that page? Also note that if you have a stable API, it's not necessary to run `sphinx-apidoc` over and over again. See http://stackoverflow.com/q/28481471/407651. – mzjn Dec 31 '15 at 10:20

How to document Python packages using Sphinx

1 Answers1

Linked