From 68259969180b31e5a7c17154a55bdf1e55d599ba Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sat, 30 May 2026 15:51:52 +0200 Subject: [PATCH] docs(naming-convention): clarify --- docs/naming_convention.rst | 51 +++++++++++++++++-------------------- docs/tutorial/dynfam.rst | 5 +--- docs/tutorial/practice1.rst | 16 +++++++----- 3 files changed, 34 insertions(+), 38 deletions(-) diff --git a/docs/naming_convention.rst b/docs/naming_convention.rst index 7cda69733..17259536b 100644 --- a/docs/naming_convention.rst +++ b/docs/naming_convention.rst @@ -1,10 +1,13 @@ -.. _namingconvention: +Naming convention +===================== + +.. _filenamingconvention: File naming convention -========================== +-------------------------- The structure files in a given folder ---------------------------------------- +'''''''''''''''''''''''''''''''''''''''''' For the sake of clarity, we put the structure definitions in separate files. It's a good way to organize your rougail structures this way, @@ -26,7 +29,7 @@ A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`f for reasons of ordering and clarity. Ordering your structure files --------------------------------- +''''''''''''''''''''''''''''''''' The order in which files are loaded is important in Rougail. In a given folder, files are loaded in alphabetical order. @@ -42,34 +45,28 @@ To facilitate classification, we have defined a standard notation for structure Where `XX` is a two digits integer followed by an hyphen, and `` is a name that describes the structure that is in this file. We advise you to adopt this convention as well. -.. _filenamingconvention: +File naming convention +''''''''''''''''''''''''''''' -Generic file naming policy ---------------------------- +The is no restriction to the `` name part of file name. But it is preferable to only use +lowercase ASCII letters, numbers and the `"_"` (undescore) character. -Here are our generic file naming conventions. +.. _namingconvention: -The regular expression that validates our file naming policy is: +Variable and family naming convention +--------------------------------------- + +The name of a variable and a family must be chosen carefully. +It is the path that will allow users to retrieve their defined values. +An obscure name will cause confusion. + +By design, you cannot use just any character to name your variable. + +The regular expression that validates our variable and family naming policy is: .. code-block:: python - NAME_REGEXP = re.compile(r"^[a-z0-9_]*$") + re.compile(r"^[a-z0-9_]*$") -You can see that it is preferable to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. +You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. The snake case typographic convention is therefore used. - -Dynamically built family naming policy ------------------------------------------- - -Regarding the :ref:`dynamically built families ` the file naming policy is slightly different. -ASCII letters, numbers and the `"_"` (undescore) character are allowed, that is we allow uppercase characters. - -Why allowing uppercase letters for a dynamic familly? -Because we have choosed to write :term:`identifiers ` in uppercase. - -.. note:: The identifier is in uppercase, but the dynamic familly name is in lowercase. - You can then choose the corresponding structure filenames in lowercase. - -.. seealso:: For more information about dynamic famillies, please have a look at the - :ref:`dynamic family tutorial ` - diff --git a/docs/tutorial/dynfam.rst b/docs/tutorial/dynfam.rst index 36772b160..d07253c52 100644 --- a/docs/tutorial/dynfam.rst +++ b/docs/tutorial/dynfam.rst @@ -180,7 +180,7 @@ This identifier is a parameter that enables us to create two families named `htt then rougail will raise a family/variable override warning. When choosing a dynamically built family name, rougail will replace spaces, accents, uppercases... - by valid character and put all in lowercase. Only ASCII and underscore ("`_`") characters are allowed. + by valid character and put all in lowercase. Have a look at the :ref:`naming convention `. As you can see here, the identifier is `HTTPS`, but the name clearly contains `https` (in lowercase). @@ -273,9 +273,6 @@ We can see that the dynamically built families that have been created: and, as we expected, containing an address and a port. -.. seealso:: Have a look at the :ref:`file naming convention ` - In order to choose a proper name to a structure file or a dynamic familiy name. - A conditional disabled variable with dynamic identifier -------------------------------------------------------- diff --git a/docs/tutorial/practice1.rst b/docs/tutorial/practice1.rst index 2ab7c98bf..876ce9b14 100644 --- a/docs/tutorial/practice1.rst +++ b/docs/tutorial/practice1.rst @@ -51,6 +51,8 @@ What do we want to be implemented .. exercise:: Exercice + You need to think about: + - choose a file name that respect the :ref:`file naming and organizing convention ` - define an appropriate variable name, have a look at our :ref:`file naming convention ` - the Firefox description is in negative mode, which is not a good practice for us, we rewrite it in positive mode @@ -73,11 +75,11 @@ Please unroll the "Solution" widget to see our solution: - this variable is true by default, - this variable shall be :term:`disabled` if the `proxy_mode` variable is set to `"No proxy"`. -.. +.. %YAML 1.2 --- version: 1.1 - + prompt_authentication: description: Prompt for authentication if password is saved default: true @@ -94,8 +96,8 @@ What do we want to be implemented .. exercise:: Exercice - You need to think about: - + You need to think about: + - the choice of a file name that respect the :ref:`file naming and organizing convention ` - in order to define an appropriate variable name, - the `description` parameter will be the Firefox description, @@ -109,7 +111,7 @@ Our solution .. type-along:: For those who follow the tutorial with the help of the git repository Now you need to checkout the :tutorial:`v1.1_131 ` version:: - + git switch --detach v1.1_131 Please unroll the "Solution" widget to see our solution: @@ -120,11 +122,11 @@ Please unroll the "Solution" widget to see our solution: :language: yaml :caption: The :file:`firefox/55-proxy_dns_socks5.yml` a Jinja conditional disabled boolean variable -.. +.. %YAML 1.2 --- version: 1.1 - + proxy_dns_socks5: description: Use proxy DNS when using SOCKS v5 default: false