From 6a87c23e2b15cfb34113d94a6e882007a69d17ed Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Wed, 29 Oct 2025 17:18:55 +0100
Subject: [PATCH] doc(typo): YAML sphinx coding standards

---
 docs/conf.py                                 |  5 ++-
 docs/documentation.rst                       | 42 ++++++++++++++++++++
 docs/index.rst                               |  3 +-
 docs/library/index.rst                       |  5 ++-
 docs/library/rougailconfig_load_from_cli.rst |  8 ++--
 5 files changed, 57 insertions(+), 6 deletions(-)
 create mode 100644 docs/documentation.rst

diff --git a/docs/conf.py b/docs/conf.py
index bcf7e46af..8d3861dfc 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,7 +31,7 @@ release = '1.0'
 
 extensions = [
         'sphinx.ext.extlinks', 'sphinx_lesson', 'sphinx.ext.todo',
-        'sphinx.ext.extlinks', 'ext.xref', 'ext.extinclude'
+        'ext.xref', 'ext.extinclude'
 ]
 
 #---- xref links ----
@@ -48,6 +48,7 @@ links = {
         'tiramisu library': ('Tiramisu library homepage', 'https://forge.cloud.silique.fr/stove/tiramisu'),
         }
 xref_links.update(links)
+
 #---- ext links ----
 # **extlinks** 'sphinx.ext.extlinks',
 # enables syntax like
@@ -55,7 +56,9 @@ xref_links.update(links)
 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'),
             }
+
 #---- options for HTML output ----
 default_role = "code"
 html_theme = "sphinx_rtd_theme"
diff --git a/docs/documentation.rst b/docs/documentation.rst
new file mode 100644
index 000000000..5aded8f0c
--- /dev/null
+++ b/docs/documentation.rst
@@ -0,0 +1,42 @@
+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
+        ...
+
diff --git a/docs/index.rst b/docs/index.rst
index 8b9bb3c42..92f638bdd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -86,7 +86,8 @@ Explained differently, Rougail allows you to easily implement an integration of
    :caption: Notes
 
    developer
-
+   documentation
+   
 .. rubric:: Index page
 
 - :ref:`genindex`
diff --git a/docs/library/index.rst b/docs/library/index.rst
index 320fa3c4a..5ab547abd 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -4,7 +4,10 @@
 Rougail is a configuration management library that allows you to load variables in a simple and convenient way.
 
 In the following examples, we will use a specific configuration of Rougail.
-You will find all the configuraiton options in :doc:`configuration`.
+
+
+.. FIXME: You will find all the configuration options in doc:`configuration`
+   find a document with all the configuration options
 
 To load the configuration you must import the `RougailConfig` class and set the `main_structural_directories` values:
 
diff --git a/docs/library/rougailconfig_load_from_cli.rst b/docs/library/rougailconfig_load_from_cli.rst
index b3948beaa..bebb22fad 100644
--- a/docs/library/rougailconfig_load_from_cli.rst
+++ b/docs/library/rougailconfig_load_from_cli.rst
@@ -18,7 +18,7 @@ Then let's create an structual file:term:`structure file` :file:`dist/00-base.ym
 .. code-block:: yaml
    :caption: the :file:`dist/00-base.yml` file content
 
-    %YAML 1.2
+    \%YAML 1.2
     ---
     version: 1.1
 
@@ -66,7 +66,8 @@ Let's execute `script.py`:
 .. code-block:: bash
 
     $ python3 script.py
-    ERROR: option "Directories where structural files are placed" is mandatory but hasn't value
+    
+    ERROR: option "Directories where structural files are placed" is mandatory but has no value
 
 As expected, the .rougailcli.yml file is not loaded because it is specific to the command line.
 
@@ -147,7 +148,7 @@ To reproduce this:
 Do this script:
 
 .. code-block:: python
-    :caption: the :file:`script.py` file content
+   :caption: the :file:`script.py` file content
 
    from rougail import Rougail, RougailConfig
    from rougail.cli.rougailconfig import load
@@ -161,5 +162,6 @@ Do this script:
        exit(1)
 
 .. code-block:: bash
+
    $ python3 script.py --main_structural_directories dist/ --step.output json --main_namespace=new_test
    {<TiramisuOption path="new_test">: {<TiramisuOption path="new_test.my_variable">: 'my_value_extra'}