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
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.
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(0, 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!