docs(naming-convention): clarify
This commit is contained in:
parent
fade50baf5
commit
6825996918
3 changed files with 34 additions and 38 deletions
|
|
@ -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 `<name>` 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>` 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 <dynfam>` 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 <identifier>` 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 <dynfam>`
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <namingconvention>`.
|
||||
|
||||
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 <filenamingconvention>`
|
||||
In order to choose a proper name to a structure file or a dynamic familiy name.
|
||||
|
||||
A conditional disabled variable with dynamic identifier
|
||||
--------------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <namingconvention>`
|
||||
- define an appropriate variable name, have a look at our :ref:`file naming convention <filenamingconvention>`
|
||||
- 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 <namingconvention>`
|
||||
- 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 <src/tag/v1.1_131/README.md>` 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue