Primer: Writing documentation for Python projects with docutils

[emuller]

For writing documentation for Python projects, I find  reStructuredText, from the  docutils project, to be a good solution. This can be automatically converted to LaTeX, HTML, or XML and is a valid format for Trac wiki pages. It is also possible to embed code-examples within it that can be automatically run using  doctest (more on doctest in a future tip-of-the-day).

A very quick primer:

Paragraphs are separated by blank lines

*italic*, **bold**, ``fixed width``

1. Numbered
2. lists

* and
* bullet
* points
  - with
  - sub-lists

For a code block, finish the previous line with ::

   >>> cool_python_function()

================
Top-level header
================

Sub-heading
===========

Sub-sub-heading
---------------

.. image:: images/logo.png

For links, add an underscore, then define the link below, e.g.,

Google_ is a cool website you may not have heard of...

.. _Google: http://www.google.com

To convert to HTML:

$ rst2html.py my_file.txt > my_file.html

To convert to LaTeX:

$ rst2latex.py my_file.text > my_file.tex

 Example of using rst in Trac wiki pages:

{{{
#!rst

.. code-block:: python

 class Test:

    def TestFunction(self):
        pass

}}}