222 lines
7.8 KiB
ReStructuredText
222 lines
7.8 KiB
ReStructuredText
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.
|
||
|