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:

Passwords
=========
General overview.


Basic requirements
------------------

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


Non-alphanumeric characters
```````````````````````````
Note some pitfalls


Administration
--------------

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:

========
Security
========

.. contents::
    :backlinks: top
    :local:

.. 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.

Comments