DOCUMENTING.md

Guidelines for documenting fastIoT

Principles

• Documentation should stay closely to the code, no external documentation of e.g. variables
• How-Tos describe the general way of doing things and reference to the used libraries, data models, …
• How-Tos may be either written in ReStructed Text (.rst-Files) or Markedly Structured Text (.md-Files)
• Docstrings need to be in RST at the moment
• Use direct references to typical Python objects as described in Cross-referencing Python objects
• A service should contain it’s docstring in the __init__.py including a reference configuration, if needed

Some hints on documenting with Sphinx

• You can find hints on the syntax for Markdown or RST
• Environment Variables can also be marked as reference, use ~~~.. envvar::MY_ENV_VAR~~~
• Mark new additions with .. versionadded::

Building the documentation

1. You can either install as a Linux package or with pip.

• Under the docs you will find the sphinx-requirements.txt to be installed in your local venv
• See Installing Sphinx for more information about sphinx.

2. Modify the .rst-files inside the source directory to your liking. There is a primer on formatting with reStructuredText in the Sphinx documentation.
3. Build the documentation inside the source directory with ./make_docs.sh