2005-01-08 by sourpoi in misc, tagged: rst restructuredtext

In a nutshell:

  • nested sections should have weaker underlines/overlines
  • if you need more than three nests of sections in a single document, rethink your document's scope
  • use a common index.txt format across different projects
  • keep a flat list of files in a single project document directory

A normal ReStructuredText document should start with a section or chapter title and oragnize itself in terms of subsections and sub-subsections. A document outlining password security might look like this:

General overview.

Basic requirements

Minimum length
A word or two about requirements vs. human nature.

Non-alphanumeric characters
Note some pitfalls


Expiry period
Automation is nice.

Failed attempts
Be nice to the help desk.

Files comprising sections or chapters of a final document should be kept in a common directory and included and ordered using an index (similar to the common index.html for default web pages). For example, a folder dedicated to security documentation could include the contents of individual files in index.txt. Here, the index sets a document title and table of contents before including the passwords.txt and permissions.txt documents:


.. contents::
    :backlinks: top

.. include:: passwords.txt

.. include:: permissions.txt

The index file should have a generic name and format to make it easy to render many projects' documentation in one run or to include several projects' documentation in a compound document.

If enough documents exist to warrant more layers, follow the same convention used for the master index:

Part title

Subpart title

Finally, don't hide documents in sub-directories. If a directory listing is hard to follow, re-think the files' naming convention.