Ticket #3 (new defect)

Opened 1 year ago

Primer: Writing documentation for Python projects with docutils

Reported by: emuller Assigned to: somebody
Priority: major Milestone:
Component: component1 Version:
Keywords: Cc:

Description

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

}}}