Contributing to the docs#

This section intend to give developers a few guidelines on how to write the documentation.

Setting up Sphinx for productive documentation#

Starting with installing the doc requirements.

Install the requirements for the docs by running:

pip install meteofrance_publicapi[doc]

Building the documentation#

From the root directory, run the command :

sphinx-build -M html ./doc ./build/sphinx

This command will parse the ./doc/ folder content and generate html files from it in the folder ./build/sphinx/html

Going further with rST#

Useful information about the rST markup :

The 4 types of documents#

There is a summary of the documentation system .

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four :

tutorials : aimed to teach new users the main principles
how-to guides : aimed to provide simple answers to recurring questions
technical reference : aimed to describe the code, and how to operate it
explanation : aimed to clarify and illuminate a particular topic.

The Secrets of each type

**The main ideas for the 4 kind of docs**#
	Tutorials	How-Tos	Technical Reference	Explanation
Oriented to	learning	a goal	information	understanding
Must	allow the newcomer to get started	show how to solve a specific problem	describe the machinery	explain
Its form	a lesson	a series of steps	dry description	discursive explanation
Analogy	teaching a small child how to cook	a recipe in a cookery book	a reference encyclopedia article	an article on culinary social history

Using Docstring#

Docstring is an important part of documentation : by keeping the documentation close to the code, it unsure that:

it can be easily updated with the function code;
it can be used in IDE for auto-completion, type hints and such.

Including Math#

Equations can easily be included in the doc, both inline :math:\frac{ \sum_{t=0}^{N}f(t,k) }{N} (that renders as \(\frac{ \sum_{t=0}^{N}f(t,k) }{N}\)) and as a block

.. math::

 \frac{ \sum_{t=0}^{N}f(t,k) }{N}

that renders as :

\[\frac{ \sum_{t=0}^{N}f(t,k) }{N}\]

Including code block#

To illustrate the use of a function, it can be interesting to add a code-block following this syntax :

.. code-block:: python

  value = myfunction(arg1, arg2)
  print(value)

that renders as:

value = myfunction(arg1, arg2)
print(value)

(you see the syntax highlighting?)

Generating new pages for new modules#

When a new module is added to the code, it is important to add a new page in the documentation.

To do so, the new file must: - be created in the ./doc/source/ folder - be named after the module name (e.g. my_module.rst) - be referenced in a doctree (usually the parent module)

You can do the first two steps easily using sphinx-apidoc : .. code-block:: bash

sphinx-apidoc -MP -e -o doc/sources meteofrance_publicapi