sphinx-localecmddoc 0.1.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 the searchpath for localecmd.Modules, see below.

Module searchpath

Now the searchpath for localecmd.Modules has to be added. This is a list of all modules within your project that contain the localecmd.Modules you want to document.

Adding the searchpath is an important step, as the extension must know where to look for the modules. The modules will be imported with importlib, meaning that the project must be on the search path of Python. The right way of doing this is to install the project in editable mode: pip install -e ..

For example, if the project name is project and modules are in cmd, write

localecmd_searchmodules = ['project.cmd']

Output directory

This is currently 'function' and cannot be changed yet.

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 = ''

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