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:: rst

    .. 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:: rst

    .. 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
        ...