diff --git a/docs/cli.rst b/docs/cli.rst index 601fe8cf4..27e103c50 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,5 +1,3 @@ -:orphan: - The Rougail Command Line Interface ======================================== @@ -10,7 +8,6 @@ Les help rougail -u yaml -h - Standard usage ----------------- @@ -142,9 +139,10 @@ Le output doc :: rougail -m structure.yml -o doc --doc.output_format github > README.md + :: - doc: + doc: Generate documentation from structural files -do [{console,asciidoc,html,github,gitlab,json}], --doc.output_format [{console,asciidoc,html,github,gitlab,json}] @@ -162,8 +160,6 @@ Le output doc --doc.no-document_a_type - - Le formatter ---------------- diff --git a/docs/configuration.rst b/docs/configuration.rst index 5f067482f..200226e88 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -40,7 +40,7 @@ The functions file The file which contains the custom functions is managed in the `functions_file` key and has the default value `/srv/rougail/functions.py`. This key can contain a list if there are several files. -.. important:: Functions must return a value, even if the variable being calculated is a :term:`multiple` variable. If the function can return a multiple value (a list), you must put the name of the function in the `multi_functions` key. +.. important:: Functions must return a value, even if the variable being calculated is a :term:`multiple ` variable. If the function can return a multiple value (a list), you must put the name of the function in the `multi_functions` key. The `auto_freeze` variable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/family.rst b/docs/family.rst index d0ef88f54..46f53e1f4 100644 --- a/docs/family.rst +++ b/docs/family.rst @@ -77,14 +77,14 @@ Parameters User information to understand the usefulness of the family. - .. seealso:: tutorial with a real world sample :ref:`description parameter ` + .. seealso:: tutorial with a real world sample :doc:`description parameter ` * - **help**, **_help** `string` - Additional help associated with the family. - .. seealso:: tutorial with a real world sample :ref:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) + .. seealso:: tutorial with a real world sample :doc:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) * - **mode**, **_mode** @@ -99,7 +99,7 @@ Parameters **Default value**: The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family. - .. seealso:: tutorial with a real world sample :ref:`mode parameter ` (the tutorial focuses on variable, but the principle is the same for a family) + .. seealso:: tutorial with a real world sample :doc:`mode parameter ` (the tutorial focuses on variable, but the principle is the same for a family) * - **type**, **_type** @@ -121,7 +121,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :ref:`hidden parameter ` + .. seealso:: tutorial with a real world sample :doc:`hidden parameter ` * - **disabled**, **_disabled** @@ -134,7 +134,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :ref:`disabled parameter ` + .. seealso:: tutorial with a real world sample :doc:`disabled parameter ` * - **dynamic**, **_dynamic** @@ -164,7 +164,7 @@ Parameters .. note:: If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_" name. - You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" `. + You can have a look at the tutorial with a real world sample :doc:`of parameter with "_" `. A family --------- @@ -187,8 +187,8 @@ Here is a simple example: You can have a look at the tutorial with a real world sample: - - :ref:`family ` - - :ref:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) + - :doc:`family ` + - :doc:`help parameter ` (the tutorial focuses on variable, but the principle is the same for a family) A dynamically built family ----------------------------- @@ -225,7 +225,7 @@ This will dynamically create two families: .. seealso:: - You can have a look at the tutorial with a real world sample :ref:`dynamically built family ` + You can have a look at the tutorial with a real world sample :doc:`dynamically built family ` Similar object sequence ------------------------- @@ -270,7 +270,7 @@ It's what we call a sequence of similar object. .. seealso:: - You can have a look at the tutorial with a real world sample :ref:`similar object sequence ` + You can have a look at the tutorial with a real world sample :doc:`similar object sequence ` A custom type family ---------------------- @@ -282,4 +282,4 @@ This custom type family can be used as many times as desired and customized as y .. seealso:: - You can have a look at the tutorial with a real world sample :ref:`family custom type ` + You can have a look at the tutorial with a real world sample :doc:`family custom type ` diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst deleted file mode 100644 index 85272b729..000000000 --- a/docs/gettingstarted.rst +++ /dev/null @@ -1,82 +0,0 @@ -:orphan: - -The variables ------------------ - -Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode` -A variable can be defined without other informations. - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml - :language: yaml - :caption: A Rougail structure file with a variable named `proxy_mode`, with a description. - :name: RougailStructureFirstVariable - -.. - %YAML 1.2 - --- - version: 1.1 - - proxy_mode: - ... - -But it's better to describe this variable: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml - :language: yaml - :caption: A Rougail structure file with a variable named `proxy_mode`, with a description. - :name: RougailStructureFirstVariableWithDescription - -.. - %YAML 1.2 - --- - version: 1.1 - - proxy_mode: # Configure Proxy Access to the Internet - ... - - -The same with a default value: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml - :language: yaml - :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value. - :name: RougailStructureFirstVariableDefault - -.. - %YAML 1.2 - --- - version: 1.1 - - proxy_mode: No proxy # Configure Proxy Access to the Internet - ... - -variable - - A :term:`variable` is a declaration unit that represents a business domain metaphor, - the most common example is that a variable that represents a configuration option - in a application, but a variable represents something more that a configuration option. - It provides a business domain specific representation unit. - -Families of variables --------------------------- - -family - - A :term:`family` is simply a container of variables and/ore some subfamilies. - -Here how a YAML structure file with a family looks like: - -.. code-block:: yaml - :caption: A :file:`hello.yml` structure sample file - - --- - version: '1.1' - world: - description: Hello world family container - name: - description: Somebody to say hello - default: rougail - -Here, we have a family named `world`. -This family contains a variable named `name` - diff --git a/docs/index.rst b/docs/index.rst index 5cfff9d81..bab7e3dd2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,11 +8,10 @@ Rougail =========== -.. todo:: définir les termes suivants +.. todo:: définir les termes suivants: 1 check.rst:9: WARNING: term not in glossary: 'validator' 2 check.rst:56: WARNING: term not in glossary: 'follower' - 3 configuration.rst:43: WARNING: term not in glossary: 'multiple' 4 family.rst:25: WARNING: label non défini: 'convention on variable names' 5 structfile.rst:89: WARNING: term not in glossary: 'variable_namespace' 6 tutorial/tutorial.rst:437: WARNING: term not in glossary: 'leadership' @@ -23,8 +22,18 @@ Rougail 11 variable.rst:154: WARNING: term not in glossary: 'required' 12 variable.rst:156: WARNING: term not in glossary: 'leader' 13 variable.rst:156: WARNING: term not in glossary: 'follower' - 14 variable.rst:186: WARNING: term not in glossary: 'multiple' - 15 variable.rst:186: WARNING: term not in glossary: 'multiple' + + +.. todo:: créer les documents suivants: + + 1 rougail/docs/family.rst:102: WARNING: unknown document: 'tutorial/mode' + 2 rougail/docs/family.rst:273: WARNING: unknown document: 'tutorial/sequence' + 3 rougail/docs/structfile.rst:89: WARNING: term not in glossary: 'variable_namespace' + 4 rougail/docs/variable.rst:163: WARNING: unknown document: 'tutorial/mode' + 5 rougail/docs/variable.rst:235: WARNING: unknown document: 'tutorial/validators' + 6 rougail/docs/variable.rst:263: WARNING: unknown document: 'tutorial/autosave' + + .. image:: images/logo.png @@ -42,14 +51,14 @@ Rougail .. toctree:: :titlesonly: - :caption: The structured files + :caption: Structure files structfile naming_convention .. toctree:: :titlesonly: - :caption: The options + :caption: Variables and families variable family @@ -60,20 +69,21 @@ Rougail .. toctree:: :titlesonly: - :caption: Load values from user datas + :caption: The values -- the user datas user_datas/index .. toctree:: :titlesonly: - :caption: The library + :caption: The library and the tools - library/index configuration - + cli + library/index + .. toctree:: :titlesonly: - :caption: Notes + :caption: Developper notes developer documentation diff --git a/docs/tags.rst b/docs/tags.rst index 009d074d3..21f0a8e63 100644 --- a/docs/tags.rst +++ b/docs/tags.rst @@ -1,5 +1,7 @@ -The variable tags -================== +The `tag` parameter's variable +================================ + +FIXME: a étoffer Here is an example: diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index 3e44bae98..b66bd59da 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -273,4 +273,4 @@ Let's recap about the user data. We can see in this Rougail CLI output that: .. seealso:: - Full documentation about :ref:`family ` + The full documentation about a :term:`family`. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 61173afa6..403e1f3fb 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -61,4 +61,5 @@ Let's dive into this **configuration options validation** use case. multiple examples practice1 + underscore_parameter whatsnext diff --git a/docs/variable.rst b/docs/variable.rst index dc423a43f..ac4d919d0 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -134,14 +134,14 @@ Parameters User information to understand the usefulness of the variable. - .. seealso:: tutorial with a real world sample :ref:`description parameter ` + .. seealso:: tutorial with a real world sample :doc:`description parameter ` * - **help** `string` - Additional help associated with the variable. - .. seealso:: tutorial with a real world sample :ref:`help parameter ` + .. seealso:: tutorial with a real world sample :doc:`help parameter ` * - **mode** @@ -160,7 +160,7 @@ Parameters - if the variable is not in a family, the variable will have a medium mode by default - a :term:`mandatory` variable without default value (calculate or not) will have the smaller mode - .. seealso:: tutorial with a real world sample :ref:`mode parameter ` + .. seealso:: tutorial with a real world sample :doc:`mode parameter ` * - **tags** @@ -179,7 +179,7 @@ Parameters `list` - List of examples to illustrate possible values for a variable - .. seealso:: tutorial with a real world sample :ref:`examples parameter ` + .. seealso:: tutorial with a real world sample :doc:`examples parameter ` * - **test** @@ -195,7 +195,7 @@ Parameters See the list of available type below. - .. seealso:: tutorial with a real world sample :ref:`type parameter ` + .. seealso:: tutorial with a real world sample :doc:`type parameter ` * - **params** @@ -204,14 +204,15 @@ Parameters See the list of available parameters for each type below. - .. seealso:: tutorial with a real world sample :ref:`params parameter ` + .. seealso:: tutorial with a real world sample :doc:`params parameter ` * - **multi** `boolean` + - The value of the variable is a list. - **Default value**: mostly `false, but there is special cases: + **Default value**: mostly `false`, but there is special cases: - the default value is a list - a variable with a variable :term:`multiple ` has default value @@ -222,7 +223,7 @@ Parameters - multi_min_length: maximum number of expected values for a multiple variable - multi_max_length: minimum number of expected values for a minimum variable - .. seealso:: tutorial with a real world sample :ref:`multi parameter ` + .. seealso:: tutorial with a real world sample :doc:`multi parameter ` * - **validators** @@ -231,7 +232,7 @@ Parameters The value of the variable will be considered invalid if the Jinja template return an error. - .. seealso:: tutorial with a real world sample :ref:`validators parameter ` + .. seealso:: tutorial with a real world sample :doc:`validators parameter ` * - **default** - Default value(s) of the variable. @@ -240,7 +241,7 @@ Parameters For a non :term:`leading` :term:`multiple ` variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable. - .. seealso:: tutorial with a real world sample :ref:`default parameter ` + .. seealso:: tutorial with a real world sample :doc:`default parameter ` * - **secret_manager** - The variable use a secret manager to get value @@ -259,7 +260,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :ref:`auto_save parameter ` + .. seealso:: tutorial with a real world sample :doc:`auto_save parameter ` * - **mandatory** @@ -272,7 +273,7 @@ Parameters **Default value**: `true` - .. seealso:: tutorial with a real world sample :ref:`mandatory parameter ` + .. seealso:: tutorial with a real world sample :doc:`mandatory parameter ` * - **empty** @@ -307,7 +308,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :ref:`hidden parameter ` (the tutorial focuses on family, but the principle is the same for a variable) + .. seealso:: tutorial with a real world sample :doc:`hidden parameter ` (the tutorial focuses on family, but the principle is the same for a variable) * - **disabled** @@ -322,7 +323,7 @@ Parameters **Default value**: `false` - .. seealso:: tutorial with a real world sample :ref:`disabled parameter ` (the tutorial focuses on family, but the principle is the same for a variable) + .. seealso:: tutorial with a real world sample :doc:`disabled parameter ` (the tutorial focuses on family, but the principle is the same for a variable) * - **frozen**