Metadata-Version: 2.4
Name: sphinx-localecmddoc
Version: 0.1.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: 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
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
```