Sphinx Documentation


Sphinx is a great tool for documenting Python, but its remarkably difficult to get started with, and (oddly enough) hard to find a good beginner’s tutorial for.

Getting Started

Run sphinx-quickstart, which will start you through the process, and interactively ask you questions, and make a docs/conf.py and a docs/Makefile for you. I don’t remember how I answered the questions.


I like to put docs in a docs folder, which is then where sphinx-quickstart will create a configuration file named conf.py and a Makefile. Then I like to have something like the following:

|- README.rst
|- docs
   |- conf.py
   |- index.rst

Readme file: README.rst

This is a standard README, that will appear on the Github page and in the documentation index file.

It should have a few sections:

Index file: docs/index.rst

This is the “welcome page”. It has two parts: the introduction (sourced from README.rst), and the Table of Contents. Here is source for it:

.. include:: ../README.rst

Full Contents

.. toctree::
    :maxdepth: 3




Indices and tables

* :ref:`genindex`

This will include the README from above, and add links to docs/example-usage.rst (make that yourself) and docs/api.rst (see below).

API file: docs/api.rst


.. automodule:: spack

# Include class `spack.Packing`, which is imported into the main package
.. autoclass:: spack.Packing

This will tell Sphinx to auto-generate documentation from the module.

Generating documentation

cd ${PACKAGE_DIR}/docs
make html

Or for more options, make help.

Read The Docs

You can also then use Read the Docs to host documentation; it will even pull from Github and build the documentation for you.


This was based on spack.