Sphinx auto-document generator for SaltStack sls files
Project description
Sphinx AutoSaltSLS provides a way to automatically document Salt .sls files (e.g. states, pillar, reactors, etc) using simple directives in the comments blocks of those files.
A comment block is identified using a block start string (default is ‘###’) and contains all subsequent lines that start with a given comment character (default is ‘#’’). The block ends when a new start string or a non-comment line is read. Directives can be given in the comment block to control how the lines are parsed.
Getting Started
The following steps will walk through how to add AutoSaltSLS to an existing Sphinx project. For instructions on how to set up a Sphinx project, see Sphinx’s documentation on Getting Started.
Installation
AutoSaltSLS can be installed through pip:
pip install sphinxcontrib-autosaltsls
Next, add and configure AutoSaltSLS in your Sphinx project’s conf.py.
extensions.append('sphinxcontrib-autosaltsls')
autosaltsls_sources = {
'states': {
'title': 'States',
'template_path': '_templates/autosaltsls/states',
},
'pillar' : {
'title': 'Pillar'
},
}
The documentation will be built into the location specified by autosaltsls_build_root (defaults to ‘.’)
To configure AutoAPI behaviour further, see the Configuration documentation.
Basic Setup
The absolute minimum setup is to set autosaltsls_sources as a list of directories under your salt fileset area (e.g. /srv/salt) and let the extension index the files it finds. Documentation pages will be created but, unless the sls files have had their document comment blocks enabled, they will say “No content”.
autosaltsls_sources = [
'states',
'pillar',
]
See Comment Block Format for more information on how to enable these.
To Do
Write proper tests
Credits
This project was based on the logic behind both readthedocs/sphinx-autoapi and Jakski/sphinxcontrib-autoyaml, so many thanks to those projects for getting me started.
[~ Dependencies scanned by PyUp.io ~ ]
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxcontrib-autosaltsls-0.7.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4d9d6d9a21eedee8c82fd806ca7bd32187487af7e21a08bb96dfb26b37f9f1eb |
|
MD5 | f5b37560d2a48977a524ac5b91e862b8 |
|
BLAKE2b-256 | 62f5c94f33716c5d84a4209a23bfd0369c71180aec4c499e7210438662069971 |
Hashes for sphinxcontrib_autosaltsls-0.7.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cf1d1f278043f6a1a0fe4dadb4289d5b3c89ae730cd7044b5f9543f63ca5e680 |
|
MD5 | 04989511c285c5fa4268c6ec31aca16d |
|
BLAKE2b-256 | 54bfdd3a657145b9de8c948fe6c0d193bf458571d33b599dd29e1f8b40dfda8c |