docs(documentation-standards): detailled use of sphinx

docs/documentation.rst

@@ -1,42 +1,224 @@
-Documentation standards
+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.
 
-YAML bloc code
+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
 -------------------
 
-If you have some YAML
+We use two complementary mechanisms to track pending work:
-The rougail YAML follows the YAML 1.2 conventions, 
-you might encounter a warning like this one::
 
-    WARNING: Le lexème du bloc_littéral ' %YAML 1.2\n ---\n version: 1.1\n\n ...' 
+- **FIXME** – keyword for things that need **correction** (bugs, typos, broken links, wrong logic)
-    en tant que "yaml" a entraîné une erreur au niveau du jeton : '%'. 
+- **``.. todo::`` directive** – for things that need to be **done** (missing sections, improvements, new features)
-    Réessayer en mode relaxé.
+
+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
 
-    .. code-block:: yaml
+    Using the Logger
-       :caption: the :file:`dist/00-base.yml` file content
+    ================
 
-        %YAML 1.2
+    Basic setup
-        ---
+    -----------
-        version: 1.1
 
-        my_variable: my_value_extra  # a simple variable
+    Add the following to your configuration:
-        ...
 
-Because the sphinx-doc tool is not YAML 1.2 ready yet. 
+    .. code-block:: python
-The solution is simple, just escape the `%` like this:
+
+        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
 
-    .. code-block:: yaml
+    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_170/firefox/60-dns_over_https.yml
-       :caption: the :file:`dist/00-base.yml` file content
+       :language: yaml
+       :caption: The :file:`firefox/60-dns_over_https.yml` with the jinja validator
 
-        \%YAML 1.2
+Explanation of options:
-        ---
-        version: 1.1
 
-        my_variable: my_value_extra  # a simple variable
+- **``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.
 

docs/tutorial/validators.rst

@@ -24,7 +24,7 @@ Validators
        git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
        git switch --detach v1.1_170
 
-A variable with custom validation
+Validating a variable's value
 -----------------------------------
 
 Now, we would like the :term:`operator` to remember not to forget the http protocol, that is to put `http://` at the beginning of our `web_address` variable's value. What if he has forgotten the http protocol? We can add a reminder in case he has forgotten.