Documentation standards

YAML bloc code

If you have some YAML 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 ...'
en tant que "yaml" a entraîné une erreur au niveau du jeton : '%'.
Réessayer en mode relaxé.

.. code-block:: yaml
   :caption: the :file:`dist/00-base.yml` file content

    %YAML 1.2
    ---
    version: 1.1

    my_variable: my_value_extra  # a simple variable
    ...

Because the sphinx-doc tool is not YAML 1.2 ready yet. The solution is simple, just escape the % like this:

.. code-block:: yaml
   :caption: the :file:`dist/00-base.yml` file content

    \%YAML 1.2
    ---
    version: 1.1

    my_variable: my_value_extra  # a simple variable
    ...