docs(documentation-standards): detailled use of sphinx
This commit is contained in:
gwen
parent
af513c6608
commit
800a61bbf4
2 changed files with 208 additions and 26 deletions
|
|
@ -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 ``:<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
|
||||
: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 <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
|
||||
: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:: <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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue