5. Documenting software projects

The objectives of this tutorial are to familiarise yourself with:

• principles for creating good documentation;

• plain text markup languages commonly used for writing documentation (Markdown and reStructuredText);

• tools for processing plain text documentation and generating output in html or pdf formats (Sphinx);

• online services for hosting documentation (ReadTheDocs); and

• methods for contributing to documentation.

Here are some examples of open-source code documented with Sphinx and hosted on the web.

• https://opencmiss-iron-tutorials.readthedocs.io

• http://libcellml.readthedocs.io/

• http://morphic.readthedocs.io/

• https://adv-prodcon.readthedocs.io/

• https://abi-eit.github.io/tetrahedralizer

Contents

• 5.1. Writing effective documentation
• 5.2. Languages
• 5.3. Documentation generation tools
• 5.4. Creating new documentation with Sphinx
• 5.5. Hosting documentation
• 5.6. Updating documentation
• 5.7. Documenting source code (TBC)