Documenting

The reference tool to build technical documentation associated with python code is Sphinx. There are at least four levels of documentation which serves different purposes:

• the scientific description of the underlying methods and tools

• the package interface for a user with basic examples.

• the package in-depth documentation for the developer

• the scientific synthesis of some studied applications

One might argue that the tests (acceptance and unit) are part of respectively the second and third points.

• Configuration
• Build
• Titles
• Structure
• Labels and references
• Indexing
• Links, Citations and Bibliography
• Generate from source
• Write math
• Illustrate
• Draw graphs