RestructuredText

The standard file format that is used in python to write technical documentation is RestructuredText.

Example

In RestructuredText what you type is not what you get. For instance the following snippet

Features
________

#. Be awesome
#. Make things faster

Installation
____________

Install **my_project** by running:

.. code-block::

   pip install my_project

is rendered to look like the following:

Features

  1. Be awesome

  2. Make things faster

Installation

Install my_project by running:

pip install my_project

Editing a document is not as straight forward as standard Word Processors, like Libre Office. The idea of using it for documentation is:

Idea

Here some good features of reStructuredText:

  • automatic formatting

  • changes are traceable with git

  • auto generated content, i.e. table of content, links

  • Speed up writing documentation (once you are familiar with RestructuredText)

Properties

And some things to keep in mind when writing your documentation

  • indention is important

  • blank lines are very important

  • 3 spaces vs. 4 spaces in python

  • supports

    • highlighting

    • lists

    • table

    • all sorts of blocks

    • images

    • hyperlinks

    • citations

    • footnotes

    • much more

  • can create multiple output formats

    • html

    • LaTEX (pdf)

    • ePub

    • manual pages

    • plain text

For a more detailed introduction on RestructuredText, please take a look at this documentation.