diff --git a/docs/documentation.rst b/docs/documentation.rst index 5aded8f0c..31b6cc794 100644 --- a/docs/documentation.rst +++ b/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 -The rougail YAML follows the YAML 1.2 conventions, -you might encounter a warning like this one:: +We use two complementary mechanisms to track pending work: - WARNING: Le lexème du bloc_littéral ' %YAML 1.2\n ---\n version: 1.1\n\n ...' - en tant que "yaml" a entraîné une erreur au niveau du jeton : '%'. - Réessayer en mode relaxé. +- **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 ``::``, 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 - :caption: the :file:`dist/00-base.yml` file content + Using the Logger + ================ - %YAML 1.2 - --- - version: 1.1 + Basic setup + ----------- - 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. -The solution is simple, just escape the `%` like this: + .. 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: .. code-block:: rst - .. code-block:: yaml - :caption: the :file:`dist/00-base.yml` file content + .. 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 - \%YAML 1.2 - --- - version: 1.1 +Explanation of options: - my_variable: my_value_extra # a simple variable - ... +- **``extinclude:: ``** – the full URL to the raw YAML file on the remote forge +- **``:language: yaml``** – enables YAML syntax highlighting in the rendered output +- **``:caption: ``** – 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. diff --git a/docs/tutorial/validators.rst b/docs/tutorial/validators.rst index 22fe966a9..b63b849dd 100644 --- a/docs/tutorial/validators.rst +++ b/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.