This extension has two types of configuration options - top-level ones that control how the extension itself works and source-specific ones that control how the sls files in a given source location should be processed.

Configuration Options

These options should be set in the Sphinx file in your documentation area.



The source areas in the Salt master’s fileset (e.g. states, pillar, etc) to be documented. This can be provided in one of two ways:

  1. As a list of paths if you want to accept all the default source settings:

    autosaltsls_sources = ['states', 'pillar']
  2. As a dict of source location to its settings (see Source Settings):

    autosaltsls_sources = {
        'states': {
            'title': 'States',
            'exclude': [
            'template_path': '_templates/autosaltsls/states',
        'pillar' : {
            'title': 'Pillar'



Default: .

Location where the generated .rst files will saved


Default: #!

Character/string used to denote lines which should be ignored when parsing a document comment block.


Default: #

Character/string used to denote the contents of a document comment block.


Default: True

Generate the genindex, modindex and search indices on the master index page when autosaltsls_write_index_page is set.


Default: ###

String used to denote the start of a document comment block.


Default: False

Comment blocks can be indented. All line parsing and processing routines will remove leading spaces before the autosaltsls_doc_prefix or autosaltsls_comment_prefix characters.


Default: ''

Location of an override master.rst_t file to be used when generating the top-level index file (See Templates).


Default: True

Remove the first space from a line within a comment block. This is to allow for the usual practice of putting a space after a comment character but where that space is not needed in the rendered output


Default: ..

The directory under which the autosaltsls_sources are located. If you place your Sphinx project alongside the sources then this can be omitted, otherwise provide the path (e.g. /srv/salt).


Default: None

Root URL to the files under the sources dirs in a source control system such as git. This is used to generate the [Source] link in the pages. If not supplied the link is suppressed.

autosaltsls_source_url_root = ''

Default: False

Generate a top-level index.rst file which has a toctree that references the source-level index files.

Source Settings

The way in which the .sls files under a source location are parsed can be controlled using the following settings when autosaltsls_sources is supplied as a dict:


Default: <autosaltsls_build_root>/<source>.

Path to put the built .rst files.


Default: sls

Sphinx role to use when creating cross-reference targets in documents. By default all sls files are referenced using the :sls: role but this can cause problems when two targets from different sources have the same name. For example, states/apache.sls and pillar/apache.sls would both have the cross reference :sls:`apache` but only one would be rendered properly.


Default: None

A list of paths relative to the source location to exclude from parsing. This can be useful where a sub-directory of states need to be documented as their own source and corresponding top-level index entry.


Default: False

Flag to expand the sls name in the document page title. For example apache/installed.sls would render as apache.installed rather than installed.


Default: ''

Prefix to add to the base sls name when rendering rst file contents.


Default: None

The location of the template files for this source (index.rst_t, main.rst_t, sls.rst_t, top.rst_t). This is deemed to be relative to the Sphinx config path unless provided as an absolute path. (See Templates).


Default: <source key>

The title to use on the index.rst page.


Default: ''

Prefix to add to the document title. This may be needed to ensure title uniqueness when using extensions like confluencebuilder.


Default: ''

Suffix to append to the document title. This may be needed to ensure title uniqueness when using extensions like confluencebuilder.


Default: None

URL location of the source code controlled files for this source. Can be supplied as a full url starting with http(s) or a path relative to autosaltsls_source_url_root.

Source Settings Example

The following is a commented example of a source dict:

autosaltsls_sources = {
    # Parse the 'states' directory under autosaltsls_sources_root
    'states': {
        # Replace the title with 'States'
        'title': 'States',
        # Exclude 'states/roles' from processing
        'exclude': [
        # Use the templates in this dir in place of the standard ones
        'template_path': '_templates/autosaltsls/states',
        # Use the expanded name in the document title
        'expand_title_name': True,
        # Append a suffix to the title
        'title_suffix': ' (states)',
    # Parse the 'pillar' directory under autosaltsls_sources_root
    # and accept all other default settings
    'pillar': {},
    # Parse the 'reactor' directory under autosaltsls_sources_root
    'reactor': {
        # Replace the title with 'Reactors'
        'title': 'Reactors',
    # Parse the 'states/roles' directory under autosaltsls_sources_root
    'states/roles': {
        # Replace the title with 'Roles'
        'title': 'Roles',
        # Point the source code control url root tote correct location
        # as it is really under 'states'
        'url_root': 'states/roles',
        # Set the build dir to be 'roles' so it ends up as a top-level
        # entry
        'build_dir': 'roles',
        # Prefix the sls names with 'roles.' as that is the state name
        # a user needs to pass to state.apply, etc
        'prefix': 'roles.',

For a more complete example, please view the example page.