From 9d5ca18bdcbbe90a84ff4c69beaa9a27b00bdee8 Mon Sep 17 00:00:00 2001 From: gwen Date: Wed, 3 Dec 2025 21:13:38 +0100 Subject: [PATCH] cleaning --- docs/dict_convention.rst | 19 --------------- docs/index.rst | 2 +- docs/naming_convention.rst | 4 +++- docs/tutorial/domainname.rst | 45 ++++++++++++++++++++++++++++++++---- 4 files changed, 45 insertions(+), 25 deletions(-) delete mode 100644 docs/dict_convention.rst diff --git a/docs/dict_convention.rst b/docs/dict_convention.rst deleted file mode 100644 index 8cb4efcd9..000000000 --- a/docs/dict_convention.rst +++ /dev/null @@ -1,19 +0,0 @@ -Structure file conventions -============================ - -Structure file naming convention ------------------------------------- - -The order of structure files is important for the order in which variables and families are created. - -The files must therefore be started with two numbers followed by a hyphen. - -For example: `00-base.xml` - -Naming convention for families and variables ------------------------------------------------ - -The only restriction on the name of families and variables is that the name must not start with the `"_"` (undescore) character. - -However, it is preferable to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. -The snake case typographic convention is therefore used. diff --git a/docs/index.rst b/docs/index.rst index 8dea784b8..f9a77874a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,7 +46,7 @@ Rougail :caption: The structured files structfile - dict_convention + naming_convention .. toctree:: :titlesonly: diff --git a/docs/naming_convention.rst b/docs/naming_convention.rst index 087e172e5..a2b895e00 100644 --- a/docs/naming_convention.rst +++ b/docs/naming_convention.rst @@ -39,6 +39,8 @@ To facilitate classification, we have defined a standard notation for structure XX-.yml -Where `XX` is a two digits integer, and `` is a name that describes +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. +Moreover, it is preferable to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. +The snake case typographic convention is therefore used. diff --git a/docs/tutorial/domainname.rst b/docs/tutorial/domainname.rst index 9e23c1253..c69ffd673 100644 --- a/docs/tutorial/domainname.rst +++ b/docs/tutorial/domainname.rst @@ -1,10 +1,10 @@ -The `domainname` and `port` types -================================== +A few types suitable for our use case +================================================ .. objectives:: Objectives - There isn't just the `string` or `integer` type, - discover new types of variables, such as `domainname` and `port`. + There isn't just the `string` or `integer` type, there are basic types + that are much more suited to our use case, such as `domainname`, `port`, and `boolean`. .. prerequisites:: Prerequisites @@ -374,6 +374,43 @@ And we have this output: We observe that, as with the `domainname` type, a number of validations are performed to ensure that the value assigned to this variable conforms to the `port` type. +A variable with type `boolean` +----------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_033` version:: + + git checkout v1.1_033 + +Let's add one more variable in the `manual` family, with a much more basic type: `boolean`. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_033/firefox/20-manual.yml + :language: yaml + :caption: A new structure file :file:`firefox/20-manual.yml` with one variable + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + ... + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +.. note:: + + - it is not necessary to declare the variable as a boolean type + this type is *inferred* by the `true` default value + + - we have decided to create a new structure file :file:`firefox/20-manual.yml`. + This is not necessary but usefull, please have a look at the :ref:`structure file organization and naming conventions ` + + + .. keypoints:: let's review the key points - we can assign a `domainname` type to a variable