add pages

docs/cli.rst

@@ -0,0 +1,29 @@
+:orphan:
+
+::
+
+    rougail --cli.versions 
+
+    tiramisu: 5.2.0a9
+    tiramisu-cmdline-parser: 0.7.0a1
+    rougail: 1.2.0a29
+    rougail-cli: 0.2.0a19
+    rougail-user-data-environment: 0.1.0a9
+    rougail-user-data-yaml: 0.2.0a11
+    rougail-output-console: 0.2.0a11
+    rougail-output-json: 0.2.0a8
+
+::
+
+    env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m structfile/proxy2.yml -u yaml  environment --yaml.filename userdata/proxy.yml -o json
+
+::
+
+    env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m structfile/proxy2.yml -u yaml --yaml.filename userdata/proxy.yml -o json --json.get manual.https_proxy --json.read_write
+    {
+      "address": "toto.fr",
+      "port": "8888"
+    }
+
+
+

docs/relative_path.rst

@@ -0,0 +1,49 @@
+:orphan:
+
+on a un path relatif, `_` ou `__` 
+
+
+https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_091~1..v1.1_091
+
+
+---
+manual:
+
+  use_for_https: true  # Also use this proxy for HTTPS
+
+  "{{ identifier }}_proxy":
+    description: "{{ identifier }} Proxy"
+    dynamic:
+      - HTTPS
+      - SOCKS
+    hidden:
+      jinja: |
+        {% if my_identifier == 'HTTPS' and _.use_for_https %}
+        HTTPS is same has HTTP
+        {% endif %}
+      params:
+        my_identifier:
+          type: identifier
+      description: |
+        in HTTPS case if "manual.use_for_https" is set to True
+
+    address:
+      description: "{{ identifier }} address"
+      default:
+        variable: __.http_proxy.address
+
+    port:
+      description: "{{ identifier }} port"
+      default:
+        variable: __.http_proxy.port
+
+    version:
+      description: SOCKS host version used by proxy
+      choices:
+        - v4
+        - v5
+      default: v5
+      disabled:
+        type: identifier
+        when: 'HTTPS'
+

docs/rw_ro_modes.rst

@@ -0,0 +1,77 @@
+:orphan:
+
+Read-write or read-only modes
+==================================
+
+The read-write mode
+--------------------
+
+When you are in the design phase, your are designing the structure file or 
+setting values is some user data files, you have the role of :term:`integrator` 
+or :term:`operator`. Then you need to have access to all the datas, even 
+those which are :term:`hidden` or :term:`disabled`\ .
+
+In this phase, the configuration shall be in `RW` mode.
+
+
+.. glossary::
+
+   read-write
+   
+       In the read-write mode (RW mode), all settings are accessible and can 
+       be modified. For example, a variable which has the `frozen` property
+       can be modified. A `hidden` or `disabled` variable is accessible.
+
+       We are in the rôle of an :term:`integrator` or an :term:`operator`.
+       We are therefore in a situation where we are **using** this configuration.
+
+The read-only mode 
+--------------------
+
+Once the configuration has beed designed, it is used. 
+The situation is different. The configuration behaves as a system. 
+
+.. glossary::
+
+   read-only
+   
+       In the read-only mode (RO mode), the configuration cannot be modified. 
+       We are **using** a configuration.
+       
+       In the usage mode, we are therefore in a situation where the configuration 
+       cannot be changed. The configuration's data are immutable. 
+       
+         
+RO or RW mode?
+---------------
+
+Here is an image which summarizes these explanations:
+
+.. image:: images/read_write.png
+
+
+How to enable 
+
+By default in `rougail-cli`, the `RO` mode is activated.
+
+If you need to enable the `RW` mode, there is an `rougail-cli` option: 
+
+.. code-block:: bash
+
+    env ROUGAIL_MANUAL.USE_FOR_HTTPS=true rougail -m structfile/proxy2.yml -u yaml environment --yaml.filename userdata/proxy.yml -o json --json.read_write
+
+The output is:
+
+.. code-block:: json
+
+    {
+      "manual": {
+        "http_proxy": {
+          "address": "toto.fr",
+          "port": "8888"
+        },
+        "use_for_https": true
+      }
+    }
+
+