rougail/docs/configuration.rst

77 lines
2.8 KiB
ReStructuredText
Raw Normal View History

2023-12-17 20:25:53 +01:00
Customizing Rougail's configuration
=======================================
The `Rougail`\ 's configuration is located in the `RougailConfig` object:
.. code-block:: python
from rougail import RougailConfig
It's just a python dictionary with different keys.
To modify it, just do like with any python dictionary:
.. code-block:: python
RougailConfig[key] = value
Configuring the dictionnaries loading
-----------------------------------------
Setting the dictionnaries folders
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two types of dictionary directories:
- the main dictionaries with the `dictionaries_dir` key. The default setting is `['/srv/rougail/dictionaries']`. This setting shall list the directories folders containing dictionaries files.
- the extra dictionaries with the `extra_dictionaries` key. The value is a dictionary with all namespaces. The key being the namespace and the value being a directory listing.
For example, to add the extra example you must do:
.. code-block:: python
RougailConfig['extra_dictionaries']['example'] = ['/dir1', '/dir2']
Dictionaries are loaded in the same order as the main dictionaries.
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.
The `auto_freeze` variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `auto_freeze` property is only applied until a specific variable becomes `True`. By default the variable name is `instantiated_module`, but it is possible to change the name of this variable via the `auto_freeze_variable` key.
Modes
~~~~~~~~
.. glossary::
mode
modes are views on variables.
Modes are customizable in Rougail. By default the modes are `basic`, `standard` and `advanced`. It is possible to change this list via the `modes_level` key.
If you change these values, consider changing the default modes of families and variables in your dictionaries.
Default mode for a family
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default mode for a family is `basic`. It is possible to change the default mode of a family via the `default_family_mode` key.
Default mode for a variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default mode for a variable is `standard`. It is possible to change the default mode of a variable via the `default_variable_mode` key.
Internal functions names
~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to add internal functions via the `internal_functions` key.