Metadata-Version: 2.4
Name: sphinx_localecmddoc
Version: 0.2.0
Summary: Sphinx extension for autodocumenting localecmd modules
Project-URL: Documentation, https://codeberg.org/jbox/sphinx_localecmddoc
Project-URL: Issues, https://codeberg.org/jbox/sphinx_localecmddoc/issues
Project-URL: Source, https://codeberg.org/jbox/sphinx_localecmddoc
Author-email: j-box <j-box@blueline.email>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Documentation :: Sphinx
Requires-Python: >=3.8
Requires-Dist: jinja2
Requires-Dist: localecmd
Requires-Dist: myst-parser
Requires-Dist: sphinx
Description-Content-Type: text/markdown

# 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:
```python
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
```python
localecmd_searchmodules = ['project.cmd']

```
### 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
```python
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.
```important
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](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). 
Alternatively, commits should be [squashed](https://docs.codeberg.org/git/squash-commits/)
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/*`