Documentation Writing Guide

This project uses Sphinx to generate documentation from reStructuredText (.rst) files. Following a few consistent conventions will keep our docs clear, maintainable, and correctly rendered.

Section title levels

Use the following underline-only characters for headings:

  • Level 1 titles (page titles): underline with ====== (equal signs)

Example:

My Page Title
=============

  • Level 2 headings (major sections): underline with ------- (dashes)

Example:

My Second-level Heading
-----------------------

  • Level 3 headings (sub-sections): underline with ~~~~~~~~~~~ (tildes)

Example:

My Third-level Heading
~~~~~~~~~~~~~~~~~~~~~~

Do not skip levels (e.g. going from a level 1 title directly to a level 3 heading).

Handling TODOs and FIXMEs

We use two complementary mechanisms to track pending work:

  • FIXME – keyword for things that need correction (bugs, typos, broken links, wrong logic)

  • ``.. todo::`` directive – for things that need to be done (missing sections, improvements, new features)

Example:

FIXME: The example below uses a deprecated function.

.. todo::
    Add a section about configuration file formats.

To show or hide todos in the rendered output, set in your conf.py:

todo_include_todos = True   # shows todos in the HTML output
# todo_include_todos = False  # hides them

When True, all .. todo:: directives appear inline. Use this for local reviews; keep it False for public releases unless you want todos visible.

Extensions

Our Sphinx configuration uses the following extensions:

extensions = [
    'sphinx.ext.extlinks',
    'sphinx_lesson',
    'sphinx.ext.todo',
]

  • ``sphinx.ext.todo`` – enables the .. todo:: directive and the todo_include_todos setting.

  • ``sphinx_lesson`` – provides lesson‑specific markup (see its documentation for details).

  • ``sphinx.ext.extlinks`` – creates short aliases for long, repetitive URLs.

General writing tips

  • Keep lines wrapped at 80–90 characters for readability in plain text.

  • Use blank lines before and after headings, lists, code blocks, and tables.

  • Prefer explicit cross-references with Sphinx roles like :ref: or :doc: over raw URLs.

  • Write in present tense and imperative mood for instructions (e.g. “Define the function”, not “The function should be defined”).

  • Use ``.. code-block::`` for syntax highlighting. Always specify the language (python, bash, json, etc.).

  • Review the rendered output with make html before committing.

File organisation

  • Place .rst files in the source/ directory (or as defined in your Sphinx conf.py).

  • One page per logical topic – split long documents into sub-pages and link them with toctree.

  • Name files with lowercase letters and hyphens instead of underscores or spaces (e.g. api-reference.rst).

Example – a typical page

Using the Logger
================

Basic setup
-----------

Add the following to your configuration:

.. code-block:: python

    import logging
    logging.basicConfig(level=logging.INFO)

Advanced filtering
~~~~~~~~~~~~~~~~~~

For more complex filtering, see :ref:`custom-filters`.

FIXME: The example above should mention log levels.

.. todo::
    Add a section about rotating log files.

For any questions about Sphinx directives or reStructuredText syntax, check the official Sphinx documentation.

Displaying YAML files

We host our data files on a remote forge. To include and display YAML files directly from that remote repository, we use a custom directive called ``extinclude``.

This directive works like the standard .. include:: but fetches content from a remote URL instead of a local file.

YAML files coming from a data repository

Use the following syntax to include a remote YAML file with syntax highlighting:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_170/firefox/60-dns_over_https.yml
   :language: yaml
   :caption: The :file:`firefox/60-dns_over_https.yml` with the jinja validator

Explanation of options:

  • ``extinclude:: <URL>`` – the full URL to the raw YAML file on the remote forge

  • ``:language: yaml`` – enables YAML syntax highlighting in the rendered output

  • ``:caption: <text>`` – adds a descriptive caption below the code block

Displaying terminal commands

To include and display a text file containing bash commands or terminal output, use the raw directive with the terminal class:

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/02/cmd_ro.txt

This fetches the remote text file and renders it with terminal-style formatting (typically a dark background, monospaced font, and command-line appearance).

Displaying HTML output

To include and display an HTML file from the remote forge, use the raw directive with the output class:

.. raw:: html
   :class: output
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/config/02/output_ro.html

This fetches the remote HTML file and embeds it directly into the generated documentation page.

Summary

Content type

Directive

Class

YAML files

.. extinclude::

:language: yaml

Terminal commands / text

.. raw:: html

:class: terminal

HTML output

.. raw:: html

:class: output

All three directives fetch content from our remote forge at build time, ensuring the documentation always displays the latest version of the referenced files.