Skip to main content

Sphinx auto-document generator for SaltStack sls files

Project description

https://img.shields.io/pypi/v/sphinxcontrib-autosaltsls.svg https://travis-ci.com/Tanoti/sphinxcontrib-autosaltsls.svg?branch=master Documentation Status Updates Python 3 https://img.shields.io/badge/code%20style-black-000000.svg

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-autosaltsls-0.5.0.tar.gz (19.2 kB view details)

Uploaded Source

Built Distribution

sphinxcontrib_autosaltsls-0.5.0-py3-none-any.whl (21.0 kB view details)

Uploaded Python 3

File details

Details for the file sphinxcontrib-autosaltsls-0.5.0.tar.gz.

File metadata

  • Download URL: sphinxcontrib-autosaltsls-0.5.0.tar.gz
  • Upload date:
  • Size: 19.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/44.0.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.1

File hashes

Hashes for sphinxcontrib-autosaltsls-0.5.0.tar.gz
Algorithm Hash digest
SHA256 5474d64a9894e6e9cea6cfe31be1deaeac86af0570ea440a2b9da85e42125764
MD5 aa92cea1801cc0cbd42228429da69776
BLAKE2b-256 c29b7362a1b1537873700fda1b63550deb0e027864960869432414ab630dce12

See more details on using hashes here.

File details

Details for the file sphinxcontrib_autosaltsls-0.5.0-py3-none-any.whl.

File metadata

  • Download URL: sphinxcontrib_autosaltsls-0.5.0-py3-none-any.whl
  • Upload date:
  • Size: 21.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/44.0.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.1

File hashes

Hashes for sphinxcontrib_autosaltsls-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f0f754d86a1eecf69dc6739eb4cf3ab649687d1e332d2e06dbc45f765c5ba5aa
MD5 c59a04e0221acdee579cd24a83a4c43c
BLAKE2b-256 895a416b569098728c48f3f7158ef60233f066b95bfa858e8c263f6bfddcf015

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page