diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 7f4eb30eb..90461bc37 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -30,7 +30,9 @@ At first glance we have a choice between five variables: .. toctree:: :titlesonly: :caption: The firefox tutorial steps + :hidden: preliminary + proxymode tutorial diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst new file mode 100644 index 000000000..30f70bc4b --- /dev/null +++ b/docs/tutorial/proxymode.rst @@ -0,0 +1,93 @@ +Firefox tutorial: the `mode_proxy` variable +------------------------------------------------ + +The `proxy` family +------------------- + +Let's create our first :term:`dictionary`. + +.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside + +We will put our dictionary files in this folder. + +Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml` + +.. code-block:: yaml + :caption: the :file:`00-proxy.yml` file + :linenos: + + --- + version: '1.1' + proxy: + description: Proxy configuration in order to have access to the internet + type: family + +We can see that we have defined a :term:`family` here, and this family is *empty* +(that is, the family container contains no variable yet). + +.. admonition:: If a family is empty + + We need to specify the :term:`family` type (line 5) here because if we don't, + the Rougail's type engine will infer it by default as a :term:`variable`. + +It's because we don't have set any :term:`variable` inside. + + +.. note:: The variables will be created in several files for educational purposes. + Obviously all the variables can be put in the same file. + + +The proxy's configuration type +---------------------------------- + +In the Firefox configuration, it is possible to define several configuration modes, +from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). + +Let's create a variable in its family with a description and a default value. +The type of this variable is a `choice` type: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_006/firefox/00-proxy.yml + :linenos: + :language: yaml + :caption: A rougail dictionnary file with a choice variable named `proxy_mode`, with a default value and a description. + :name: RougailDictionaryFirstVariableChoiceType + +.. glossary:: + + mandatory + + A variable is mandatory when a value is required, that is, `None` is not an option. + +The `proxy_mode` variable here, implicitely requires a value. It is a mandatory variable. + +It shall have a value, but what if the user *does not* specify any value? +There is a possibility of setting a default value, wich is set as `No proxy` by default. + +.. glossary:: + + choice type + + The `proxy_mode` setting is "choice" (`type: choice`) means that + there is a list of available values that can be selected. + +We say that the `proxy_mode` variable is *constrained* (by the `choice` type). + +We have the list of the possible (authorized) values: + +- `No proxy` +- `Auto-detect proxy settings for this network` +- `Use system proxy settings` +- `Manual proxy configuration` +- `Automatic proxy configuration URL` + +Now let's test our first two dictionaries: + +>>> from rougail import Rougail, RougailConfig +>>> from pprint import pprint +>>> RougailConfig['dictionaries_dir'] = ['dict'] +>>> rougail = Rougail() +>>> config = rougail.get_config() +>>> config.property.read_only() +>>> pprint(config.value.get(), sort_dicts=False) +{'rougail.proxy.proxy_mode': 'No proxy'} + diff --git a/docs/tutorial/tutorial.rst b/docs/tutorial/tutorial.rst index badc975ca..b50fd8bee 100644 --- a/docs/tutorial/tutorial.rst +++ b/docs/tutorial/tutorial.rst @@ -1,96 +1,5 @@ -The Firefox proxy configuration -------------------------------------------- - -The `proxy` family -------------------- - -Let's create our first :term:`dictionary`. - -.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside - -We will put our dictionary files in this folder. - -Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml` - -.. code-block:: yaml - :caption: the :file:`00-proxy.yml` file - :linenos: - - --- - version: '1.1' - proxy: - description: Proxy configuration in order to have access to the internet - type: family - -We can see that we have defined a :term:`family` here, and this family is *empty* -(that is, the family container contains no variable yet). - -.. admonition:: If a family is empty - - We need to specify the :term:`family` type (line 5) here because if we don't, - the Rougail's type engine will infer it by default as a :term:`variable`. - -It's because we don't have set any :term:`variable` inside. - - -.. note:: The variables will be created in several files for educational purposes. - Obviously all the variables can be put in the same file. - - -The proxy's configuration type ----------------------------------- - -In the Firefox configuration, it is possible to define several configuration modes, -from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). - -We're gonna create a first variable in this family with "Proxy mode" as the description. -Let's create a second :file:`dict/01-proxy_mode.yml` file. - -.. code-block:: yaml - :caption: the :file:`001-proxy_mode.yml` file - :linenos: - - --- - version: '1.1' - proxy: - proxy_mode: - description: Proxy mode - type: choice - choices: - - No proxy - - Auto-detect proxy settings for this network - - Use system proxy settings - - Manual proxy configuration - - Automatic proxy configuration URL - default: No proxy - -The `proxy_mode` variable requires a value (that is, `None` is not an option). -It shall have a value, but what if the user *does not* specify any value? -There is line 13, a possibility of setting a default value, wich is `No proxy` as the default. - -The `proxy_mode` setting is "choice" (`type: choice`) means that -there is a list of available values that can be selected. -We say that the `proxy_mode` variable is *constrained* (by choices). - -Line 8 to 12, we have the list of the possible (authorized) values: - -- No proxy -- Auto-detect proxy settings for this network -- Use system proxy settings -- Manual proxy configuration -- Automatic proxy configuration URL - -Now let's test our first two dictionaries: - - ->>> from rougail import Rougail, RougailConfig ->>> from pprint import pprint ->>> RougailConfig['dictionaries_dir'] = ['dict'] ->>> rougail = Rougail() ->>> config = rougail.get_config() ->>> config.property.read_only() ->>> pprint(config.value.get(), sort_dicts=False) -{'rougail.proxy.proxy_mode': 'No proxy'} +The Firefox proxy: the manual configuration +------------------------------------------------ The manual mode ------------------