Configuration¶
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 conf.py
file in your documentation area.
Required¶
-
autosaltsls_sources
¶ 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:
As a list of paths if you want to accept all the default source settings:
autosaltsls_sources = ['states', 'pillar']
As a dict of source location to its settings (see Source Settings):
autosaltsls_sources = { 'states': { 'title': 'States', 'exclude': [ 'roles', ], 'template_path': '_templates/autosaltsls/states', }, 'pillar' : { 'title': 'Pillar' }, }
Optional¶
-
autosaltsls_build_root
¶ Default:
.
Location where the generated .rst files will saved
-
autosaltsls_comment_ignore_prefix
¶ Default:
#!
Character/string used to denote lines which should be ignored when parsing a document comment block.
-
autosaltsls_comment_prefix
¶ Default:
#
Character/string used to denote the contents of a document comment block.
-
autosaltsls_display_master_indices
¶ Default:
True
Generate the
genindex
,modindex
andsearch
indices on the master index page whenautosaltsls_write_index_page
is set.
-
autosaltsls_doc_prefix
¶ Default:
###
String used to denote the start of a document comment block.
-
autosaltsls_indented_comments
¶ Default:
False
Comment blocks can be indented. All line parsing and processing routines will remove leading spaces before the
autosaltsls_doc_prefix
orautosaltsls_comment_prefix
characters.
-
autosaltsls_index_template_path
¶ Default:
''
Location of an override
master.rst_t
file to be used when generating the top-level index file (See Templates).
-
autosaltsls_remove_first_space
¶ 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
-
autosaltsls_sources_root
¶ 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
).
-
autosaltsls_source_url_root
¶ 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 = 'https://github.com/myuser/saltfiles'
-
autosaltsls_write_index_page
¶ 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:
-
build_dir
¶ Default:
<autosaltsls_build_root>/<source>
.Path to put the built .rst files.
-
cross_ref_role
¶ 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
andpillar/apache.sls
would both have the cross reference:sls:`apache`
but only one would be rendered properly.
-
exclude
¶ 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.
-
expand_title_name
¶ Default:
False
Flag to expand the sls name in the document page title. For example
apache/installed.sls
would render asapache.installed
rather thaninstalled
.
-
prefix
¶ Default:
''
Prefix to add to the base sls name when rendering rst file contents.
-
template_path
¶ 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).
-
title
¶ Default:
<source key>
The title to use on the index.rst page.
-
title_prefix
¶ Default:
''
Prefix to add to the document title. This may be needed to ensure title uniqueness when using extensions like
confluencebuilder
.
-
title_suffix
¶ Default:
''
Suffix to append to the document title. This may be needed to ensure title uniqueness when using extensions like
confluencebuilder
.
-
url_root
¶ 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 toautosaltsls_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': [
'roles',
],
# 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.