sphinx-localecmddoc 0.3.0

Sphinx extension for autodocumenting localecmd modules

sphinx-localecmddoc

Sphinx extension for autodocumenting localecmd modules The extension is hard-coded to generate markdown to be parsed with the myst-parser.

Install

The commands assume that your virtual environment is activated in the terminal. The installation will also install the needed dependencies if not present:

• Sphinx
• Myst-parser
• Localecmd (which is needed for what to document)

Install from git (not recommended, but only option)

To install the package and its dependencies, run

pip install sphinx-localecmddoc @ git+https://codeberg.org/jbox/sphinx-localecmddoc.git

Remember to add the dependency to the pyproject.toml (or equvalent)

Usage and configuration

The guide assumes that you already have set up sphinx with myst-parser.

Within the conf.py, add the extension to the extension list:

extensions = [
...
    'localecmddoc',
...
]

You must also add localecmd.Modules to document, see below.

Module selection

To select which localecmd.Modules to document, include them to the 'localecmd_modules' dict. For example, if python imports the module as project.cmd, write

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.

The module paths are python import paths and may specify a module or a localecmd.Module within a module. In both cases the module is imported and any side effects from that will apply.

Output directory

The output directory is set with localecmd_outdir. As a default, this is 'functions', meaning that the output will go into subdirectory 'functions' of the sphinx built output. Remember to add the the index file of that folder to any of your toctrees!

To change the output directory to for example, 'commands', write

localecmd_outdir = 'commands'

Name of builtin module

Localecmd has some builtin commands. These are included in the generated documentation under the name 'core' by default. This name can be changed with localecmd_builtins_modulename, for example 'builtins':

localecmd_builtins_modulename = 'builtins'

To not generate the documentation for the builtin commands, set the variable to an empty string:

localecmd_builtins_modulename = ''

Python code block removal

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

The reason to do this is that the user looking for the API of the command and its example, not examples if its implementation under the hood.

This option is True by default. To turn this off and keep all code blocks in the docstrings, set it to False:

localecmd_remove_python_code_blocks = False

Example language

The setting 'localecmd_codeblocks_language' controls the language of lcmd-example outputs. See below.

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. As a default, this is set to 'sphinx', meaning using the language from 'language' setting in conf.py.

The selected language must exist, else errors will be raised.
One can use the fallback language which always works.

Create target for lcmd-example directives

The setting 'localecmd_target_codeblocks' adds a target node for all lcmd-example codeblocks. This is at current not in use and also False by default.

Develop

git clone https://codeberg.org/jbox/sphinx-localecmddoc.git
cd sphinx-localecmddoc
python3 -m venv .venv --prompt sphinx-localecmddoc
source .venv/bin/activate
pip install -U pip
pip install -e . --group dev
pre-commit install

Commit messages

Commit messages should follow conventional angular style. Alternatively, commits should be squashed before merging with main branch. The reason is that the changelog can then be created automatically.

To get help with writing the commit messages, you can use commitizen by running cz commit instead of git commit. If a commit fails because of formatting, check in those changes with git add and rerun commiting with cz commit --retry. You may want to review the change with git diff(tool) before adding.

Write the commit messages as you would like to see it in the changelog since that is the reason for these guidelines.

The sphinx-localecmddoc package at current does not specify scopes for the commits.

Publishing new version

1. Update the main branch with all changes that should be included.
2. On the main branch, run cz bump --dry-run to check that updating the version works and that changelog is updated properly
3. Actually bump the version: cz bump
4. Build and upload the package to Pypi python -m build; twine upload dist/*