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 ``::``, 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 `_. 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:: ``** – 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.