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:

.. code-block:: rst

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

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

Example:

.. code-block:: rst

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

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

Example:

.. code-block:: rst

    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:

.. code-block:: rst

    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``:

.. code-block:: python

    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:

.. code-block:: python

    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.

External links (extlinks)
~~~~~~~~~~~~~~~~~~~~~~~~~

The ``extlinks`` extension defines convenient shortcuts. For each alias you write ``:<alias>:<suffix>``, and Sphinx expands it into a full URL.

Our configuration:

.. code-block:: python

    extlinks = {
        'source': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/%s',
                   'source: %s'),
        'tiramisu': ('https://tiramisu.readthedocs.io/en/latest/%s', 'tiramisu: %s'),
        'tutorial': ('https://forge.cloud.silique.fr/stove/rougail-tutorials/%s', 'tutorial %s'),
    }

Usage examples:

- ``:source:`v1.1_010/firefox/00-proxy.yml` `` → links to the raw file at that tag, displayed as ``source: v1.1_010/firefox/00-proxy.yml``
- ``:tiramisu:`configuration.html``` → links to the Tiramisu documentation, displayed as ``tiramisu: configuration.html``
- ``:tutorial:`README.md``` → links to the rougail-tutorials file, displayed as ``tutorial README.md``

The first string in each tuple is the URL pattern (the ``%s`` is replaced by your custom text). The second string is the visible link title (where ``%s`` is again replaced by your custom text).

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
------------------------

.. code-block:: rst

    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 <https://www.sphinx-doc.org/>`_.

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:

.. code-block:: rst

    .. 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:

.. code-block:: rst

    .. 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:

.. code-block:: rst

    .. 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.

