# Usage and configuration options
This page describes the directives and configuration options of sphinx-localecmd.
## lcmd-example directive
This is a directive like a code block, but for a localecmd transcript.
To use this, put in the commands. Sphinx will run them and insert the output.

```
:::{lcmd-example}
help quit
:::
```
gives
:::{lcmd-example}
help quit
:::


The language of the cli is specified with {confval}`localecmd_codeblocks_language` in the config.

## lcmd-examplelist directive
This outputs an overview over all run uses of the lcmd-example directive.
This directive is useful for testing and checking that things work.

```
:::{lcmd-examplelist}
:::
```
gives
:::{lcmd-examplelist}
:::


The language of the cli is specified with {confval}`localecmd_codeblocks_language` in the config.

## Configuration options

::::{confval} localecmd_modules
:type: dict[str, str]
:default: {'localecmd.builtins': 'core'}

Selects which localecmd.Modules to document.
The key gives the import path to the module and the value its display name in the docs.
An error is raised it the value is empty.

There are three ways to give the module import path:

1. A Python module to convert to a localecmd.Module. 
The conversion wil be done directly and no options can be specified except for module name.
2. A localecmd.Module within a Python module. This will be imported and used directly after name is changed.
3. An importable function which takes no arguments and returns a list of localecmd modules.
In this case all modules in the list will be used directly without changing anything.
For clarity, this should be mentioned in the conf.py. 

For example, if python imports the module as `project.cmd`, write
```{code} python
localecmd_modules = {
    'localecmd.builtins': 'core',
    'project.cmd': 'project',
    }
```
Then the localecmd.builtins documentation will be in localecmd_outdir/core
and the additional commands in localecmd_outdir/project.

::::

::::{confval} localecmd_outdir
:type: str
:default: 'functions'

Directory of autogenerated module documantation.
Relative to sphinx output directory.

:::{hint}
Remember to add the the index file of that folder to a toctree.
:::
::::

:::{confval} localecmd_remove_python_code_blocks
:type: bool
:default: True

Specifies that python code blocks should be removed from automatic generation of 
localecmd module documentation.
Code blocks of other languages are passed.

The reason to remove Python code blocks is that the user is looking for the API 
of the command and its example, 
not examples if its implementation under the hood.
:::

:::{confval} localecmd_ignore_codeblocks_in_files
:type: str
:default: ''

Regular expression of file names where lcmd-example codeblocks should not be run or displayed.
If empty (default), all examples are shown.
:::

::::{confval} localecmd_target_codeblocks
:type: bool
:default: True

If localecmd example code blocks should get target attributes such that they can be referenced to.
::::

:::{confval} localecmd_codeblocks_language
:type: str
:default: 'sphinx'

What language to use for the CLI in and outputs.
This language must be known to the CLI (by having corresponding subfolders and files of `locale` folder)
If set to 'sphinx', the value is taken from the value of `langauge` instead.
:::

::::{confval} localecmd_localedir
:type: str
:default: 'locale'

In which folder localecmd should look for locale files.
:::{note}
The configuration of locale may change at some point.
:::
::::

:::{confval} localecmd_additional_domains
:type: list[str]
:default: []

Which gettext domains to include in CLI in addition to those specified by localecmd.
Use the same as the application uses. Typically, this is `messages` or similar.
:::