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
¤ help quit
quit ⠀
Terminate program
:raises SystemExit: Always
The language of the cli is specified with 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
Overview over localecmd code block examples
Below code example block is on page configuration.md, line 13
¤ help quit
quit ⠀
Terminate program
:raises SystemExit: Always
The language of the cli is specified with localecmd_codeblocks_language in the config.
Configuration options¶
- 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:
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.
A localecmd.Module within a Python module. This will be imported and used directly after name is changed.
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, writelocalecmd_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.
- 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.
- 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.
- localecmd_ignore_codeblocks_in_files¶
- Type:
- str
Regular expression of file names where lcmd-example codeblocks should not be run or displayed. If empty (default), all examples are shown.
- localecmd_target_codeblocks¶
- Type:
- bool
- Default:
- True
If localecmd example code blocks should get target attributes such that they can be referenced to.
- 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
localefolder) If set to ‘sphinx’, the value is taken from the value oflangaugeinstead.
- 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.
- 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
messagesor similar.