stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

docs(proofreading): doc release preparation

Browse source
This commit is contained in:
gwen 2026-06-01 12:36:47 +02:00
parent c0308145d5
commit e40ade0b64
9 changed files with 56 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/cli.rst
View file

@ -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
----------------

2
docs/configuration.rst
View file

@ -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 <multi>` 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

22
docs/family.rst
View file

@ -77,14 +77,14 @@ Parameters
User information to understand the usefulness of the family.
.. seealso:: tutorial with a real world sample :ref:`description parameter <tutorial/family>`
.. seealso:: tutorial with a real world sample :doc:`description parameter <tutorial/family>`
* - **help**, **_help**
`string`
- Additional help associated with the family.
.. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
.. seealso:: tutorial with a real world sample :doc:`help parameter <tutorial/examples>` (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 <tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family)
.. seealso:: tutorial with a real world sample :doc:`mode parameter <tutorial/mode>` (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 <tutorial/properties>`
.. seealso:: tutorial with a real world sample :doc:`hidden parameter <tutorial/properties>`
* - **disabled**, **_disabled**
@ -134,7 +134,7 @@ Parameters
**Default value**: `false`
.. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>`
.. seealso:: tutorial with a real world sample :doc:`disabled parameter <tutorial/properties>`
* - **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 "_<parameter>" name.
You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" <tutorial/underscore_parameter>`.
You can have a look at the tutorial with a real world sample :doc:`of parameter with "_" <tutorial/underscore_parameter>`.
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 <tutorial/family>`
- :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)
- :doc:`family <tutorial/family>`
- :doc:`help parameter <tutorial/examples>` (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 <tutorial/dynfam>`
You can have a look at the tutorial with a real world sample :doc:`dynamically built family <tutorial/dynfam>`
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 <tutorial/sequence>`
You can have a look at the tutorial with a real world sample :doc:`similar object sequence <tutorial/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 <tutorial/family>`
You can have a look at the tutorial with a real world sample :doc:`family custom type <tutorial/family>`

82
docs/gettingstarted.rst
View file

@ -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`

32
docs/index.rst
View file

@ -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

6
docs/tags.rst
View file

@ -1,5 +1,7 @@
The variable tags
==================
The `tag` parameter's variable
================================
FIXME: a étoffer
Here is an example:

2
docs/tutorial/family.rst
View file

@ -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 <family>`
The full documentation about a :term:`family`.

1
docs/tutorial/index.rst
View file

@ -61,4 +61,5 @@ Let's dive into this **configuration options validation** use case.
multiple
examples
practice1
underscore_parameter
whatsnext

29
docs/variable.rst
View file

@ -134,14 +134,14 @@ Parameters
User information to understand the usefulness of the variable.
.. seealso:: tutorial with a real world sample :ref:`description parameter <tutorial/preliminary>`
.. seealso:: tutorial with a real world sample :doc:`description parameter <tutorial/preliminary>`
* - **help**
`string`
- Additional help associated with the variable.
.. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>`
.. seealso:: tutorial with a real world sample :doc:`help parameter <tutorial/examples>`
* - **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 <tutorial/mode>`
.. seealso:: tutorial with a real world sample :doc:`mode parameter <tutorial/mode>`
* - **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 <tutorial/examples>`
.. seealso:: tutorial with a real world sample :doc:`examples parameter <tutorial/examples>`
* - **test**
@ -195,7 +195,7 @@ Parameters
See the list of available type below.
.. seealso:: tutorial with a real world sample :ref:`type parameter <tutorial/types>`
.. seealso:: tutorial with a real world sample :doc:`type parameter <tutorial/types>`
* - **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 <tutorial/types>`
.. seealso:: tutorial with a real world sample :doc:`params parameter <tutorial/types>`
* - **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 <multi>` 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 <tutorial/multiple>`
.. seealso:: tutorial with a real world sample :doc:`multi parameter <tutorial/multiple>`
* - **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 <tutorial/validators>`
.. seealso:: tutorial with a real world sample :doc:`validators parameter <tutorial/validators>`
* - **default**
- Default value(s) of the variable.
@ -240,7 +241,7 @@ Parameters
For a non :term:`leading` :term:`multiple <multi>` 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 <tutorial/preliminary>`
.. seealso:: tutorial with a real world sample :doc:`default parameter <tutorial/preliminary>`
* - **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 <tutorial/autosave>`
.. seealso:: tutorial with a real world sample :doc:`auto_save parameter <tutorial/autosave>`
* - **mandatory**
@ -272,7 +273,7 @@ Parameters
**Default value**: `true`
.. seealso:: tutorial with a real world sample :ref:`mandatory parameter <tutorial/nullable>`
.. seealso:: tutorial with a real world sample :doc:`mandatory parameter <tutorial/nullable>`
* - **empty**
@ -307,7 +308,7 @@ Parameters
**Default value**: `false`
.. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
.. seealso:: tutorial with a real world sample :doc:`hidden parameter <tutorial/properties>` (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 <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
.. seealso:: tutorial with a real world sample :doc:`disabled parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
* - **frozen**