rougail/docs/tutorial/modes.rst

Modes
=========

.. objectives:: Objectives

   For information on the concept we will be using in this section, please refer to
   the definition of the :term:`mode` in the documentation, 
   and you can read all the :ref:`description of the modes in the structuring data point of view <structured_data_mode>`.

.. prerequisites:: Prerequisites

    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.

    - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
      by checking out the corresponding tag of the `rougail-tutorials` git repository.
      Each tag corresponds to a stage of progress in the tutorial.
      Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.

    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
    this workshop page corresponds to the tag :tutorial:`v1.1_150 <src/tag/v1.1_150/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach v1.1_150

A variable in avanced mode
---------------------------

To specify the various possible modes, we must declare them on the command line
with the `--modes_level` command line option:

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_150/config/01/cmd_ro.txt

..
    rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml


Next, we can set a mode parameter with a value from the list: `basic`, `standard`, `advanced`.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_150/firefox/55-proxy_dns_socks5.yml
   :language: yaml
   :caption: The `proxy_dns_socks5` variable in the :file:`firefox/55-proxy_dns_socks5.yml` file

..
    %YAML 1.2
    ---
    version: 1.1

    proxy_dns_socks5:
      description: Use proxy DNS when using SOCKS v5
      mode: advanced
      default: false
      disabled:
        jinja: |-
          {{ _.manual.socks_proxy.version is propertyerror or _.manual.socks_proxy.version == 'v4' }}
        return_type: boolean
        description: |-
          if "_.manual.socks_proxy.version" is accessible and equals "v4"
    ...

Here, we have set the mode to `advanced` for the `proxy_dns_socks5` variable
because we want to classify it as a variable intended for use by advanced users.

.. questions:: What is it actually used for? 

   Well, to begin with, reading the structure file provides a clear piece of information:
   this variable is intended to be manipulated by an experienced user.

Furthermore, if you integrate Rougail as a library into your business applications,
you will have access to different types of views corresponding to each mode.

A useful application within Rougail itself involves filtering the display of certain 
variables when generating documentation, based on the mode.

In our case, this makes it possible to generate documentation for standard users
where the `proxy_dns_socks5` won't be present,
and a different, more detailed documentation for advanced users
where the `proxy_dns_socks5` will be explained in detail.

.. seealso:: Look at the :ref:`different ways to document a variable with Rougail <documented_variable>`
             in this tutorial.

.. keypoints:: let's review the key points

    We have seen the benefits of assigning modes to a variable to define 
    documentations targeted at specific users.