Sphinx – Documentation for Python

Python is a wonderful language also because of the awesome tools that are available.

One of which is Sphinx. It is like markdown, but even more powerful, with cross referencing of pages and autogeneration of doc for python code.

Start with installing Sphinx.

$ sudo easy_install -U Sphinx

Create sphinx docs in your project.

$ cd /path/to/project/docs/
$ sphinx-quickstart

Write your documentation (eg. quick start guide) in your index.rst. Sphinx uses reStructured Text (a kind of text formatting). Refer to this quick tutorial and a handy cheatsheet.

Cross reference your documentation. You can across to arbitrary location with :ref:`my-label-name ` or across files with :doc:`my-doc-name`

.. _my-reference-label:
 
Section to cross-reference
--------------------------
 
This is the text of the section.
 
It refers to the section itself, see :ref:`my-reference-label`.

Finally, generate the HTML files.

make html

Lastly, Sphinx can automatically generate your module and classes, using your docstrings. That way, you can write your documentation in your python files (and not again in Sphinx doc). To do that, you have to edit Sphinx conf.py to add the path to your modules to sys.path.

# Load the source for autodoc
sys.path.insert(, os.path.abspath(os.path.join(os.getcwd(), '..')))

With that, you can automatically generate doc for a class.

.. automodule:: mymodule.something
 
.. autoclass:: MyClass
    :members:

This is a short introduction guide to Sphinx. There’s obviously more, with cases of authors writing books using Sphinx!

TAGGED WITH

python