From 6a641af5635f77be3fd53d86ebfc748023e496fe Mon Sep 17 00:00:00 2001 From: gwen Date: Sat, 6 Jun 2026 19:07:58 +0200 Subject: [PATCH] docs(path): relative and full path proofreading --- docs/structured_data/index.rst | 1 + docs/structured_data/path.rst | 44 +++++++++++++++++++--------------- docs/tutorial/calculated.rst | 7 +++++- docs/tutorial/properties.rst | 5 +++- docs/user_data/index.rst | 6 ++--- 5 files changed, 39 insertions(+), 24 deletions(-) diff --git a/docs/structured_data/index.rst b/docs/structured_data/index.rst index 2e26768d3..d64b83b7b 100644 --- a/docs/structured_data/index.rst +++ b/docs/structured_data/index.rst @@ -13,3 +13,4 @@ Common informations about structured data calculation Value validations condition + path diff --git a/docs/structured_data/path.rst b/docs/structured_data/path.rst index 42f4ba9a1..0ecc81cd8 100644 --- a/docs/structured_data/path.rst +++ b/docs/structured_data/path.rst @@ -1,9 +1,14 @@ + +.. index:: path, variable's relative path, variable's full path + +.. _variablepath: + Full or relative path ===================== To access a variable, it is necessary to know which family or subfamily it belongs to. -Let's create some variables to illustrate the point. +Let's create some variables to illustrate this point. .. code-block:: yaml @@ -21,17 +26,17 @@ Let's create some variables to illustrate the point. my_third_variable: # My third variable - my_forth_variable: # My forth variable + my_fourth_variable: # My forth variable ... So we have three variables. -Here full path are: +Here the full paths are: -- my_family.my_sub_family.my_first_variable -- my_family.my_sub_family.my_second_variable -- my_family.my_third_variable -- my_forth_variable +- `my_family.my_sub_family.my_first_variable` +- `my_family.my_sub_family.my_second_variable` +- `my_family.my_third_variable` +- `my_fourth_variable` But in calculation it's often better to use :term:`relative path`. @@ -40,24 +45,25 @@ But in calculation it's often better to use :term:`relative path`. relative path In a calculation definition, a relative path defines the location of a variable relative to the family of the variable where the parameter is calculated. - Instead of starting from the root, it uses references like _. (current family), __. (parent family), ___. (sub parent family) and so on. + Instead of starting from the root, it uses references like `_. (current family)`, `__. (parent family)`, `___. (sub parent family)` and so on. Relative paths are shorter and portable across custom type. -Now define :term:`relative path` from the `my_first_variable` variable: +Now we can define the :term:`relative path` from the `my_first_variable` variable: -- _.my_second_variable -- __.my_third_variable -- ___.my_third_variable +- `_.my_second_variable` +- `__.my_third_variable` +- `___.my_fourth_variable` From the `my_third_variable`: -- _.my_sub_family.my_first_variable -- _.my_sub_family.my_second_variable -- __.my_third_variable +- `_.my_sub_family.my_first_variable` +- `_.my_sub_family.my_second_variable` +- `__.my_fourth_variable` -Finally from `my_forth_variable`: +Finally from the `my_fourth_variable`: + +- `_.my_family.my_sub_family.my_first_variable` +- `_.my_family.my_sub_family.my_second_variable` +- `_.my_family.my_third_variable` -- _.my_family.my_sub_family.my_first_variable -- _.my_family.my_sub_family.my_second_variable -- _.my_family.my_third_variable diff --git a/docs/tutorial/calculated.rst b/docs/tutorial/calculated.rst index 01b42fe9f..95f6837f8 100644 --- a/docs/tutorial/calculated.rst +++ b/docs/tutorial/calculated.rst @@ -160,7 +160,7 @@ And here is the :file:`firefox/20-manual.yml` structure file where the calculate We can see here that the `address` variable's default value is conditionned by the `__.http_proxy.address` variable's value. The target variable is `manual.http_proxy.address`. -.. note:: The `__.` is a :term:`relative path` notation and means the parent path of the current subfamily path. +.. seealso:: The `__.` is a :term:`relative path` notation and means the parent path of the current subfamily path. In the python quasi algorithmic notation we could say that: @@ -170,6 +170,9 @@ The target variable is `manual.http_proxy.address`. This is true only because in our use case `http_proxy.address` is located in the same `manual` subfamiliy than `https_proxy.address`. + + Have a look at the :ref:`variablepath` page for more details. + We then say that the `manual.https_proxy.address` and the `manual.https_proxy.port` default values are *calculated*. @@ -266,3 +269,5 @@ By interpreting the results of this standard output, we can see that even if a v - the `_.` notation means the current path of the family you're currently in - the `__.` notation means the parent path of the current subfamily path. + Have a look at the :ref:`variablepath` page for more details. + diff --git a/docs/tutorial/properties.rst b/docs/tutorial/properties.rst index 26d60610d..cf7d74015 100644 --- a/docs/tutorial/properties.rst +++ b/docs/tutorial/properties.rst @@ -265,7 +265,7 @@ will be used to dynamically enable or disable our `manual` family. We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. The target variable is `_.proxy_mode`. -.. note:: The `_.` is a :term:`relative path` notation and means the current path of the family you're currently in. +.. seealso:: The `_.` is a :term:`relative path` notation and means the current path of the family you're currently in. In the python quasi algorithmic notation we could say that: @@ -275,6 +275,9 @@ The target variable is `_.proxy_mode`. This is true only because in our use case `proxy_mode` is located on the root path. + Have a look at the :ref:`variablepath` page for more details. + + Now regarding the `when_not` parameter, this means that if the target variable's value is `Manual proxy configuration` then the `manual` familiy **will not** be disabled (that is, it will be **enabled**). diff --git a/docs/user_data/index.rst b/docs/user_data/index.rst index 12f2715c3..f1bd642eb 100644 --- a/docs/user_data/index.rst +++ b/docs/user_data/index.rst @@ -1,11 +1,11 @@ User data description ====================== -Rougail is a collections of subproject to adjust functionalities to your needs. +Rougail is a collections of subproject in order to adjust functionalities to your needs. -User datas is one of category of subjects. The goal is to setup variable with value define by user. +User datas is one of category of subjects. The goal is to setup variable with value defined by the user. -There is differents user datas types: +There are different user datas types: .. toctree:: :titlesonly: