AutoSaltSLS Code

This is an autodoc rendering of the AutoSaltSLS extension code for thos of you who are interested in how the code works.

autosaltsls

Sphinx Auto-SaltSLS top-level extension

autosaltsls.config_autosaltsls(app, config)

Create custom source-specific Sphinx role/object types

autosaltsls.run_autosaltsls(app)

Load AutoSaltSLS data from the filesystem

autosaltsls.setup(app)

Setup the Sphinx app with the default config values and add the sls object type.

autosaltsls.mapper

AutoSaltSLS mapper class

class autosaltsls.mapper.AutoSaltSLSMapper(app, source, settings)

Mapper to read sls files from a source location and to generate the relevant .rst files.

app

Sphinx app instance

source

Source key (e.g. ‘states’)

settings

Source settings from conf.py for the specified key

load()

Read the files associated with the sls objects and parse their comment blocks

other_files

Return the list of sls objects not marked as top files

Returns:list

scan()

Scan the source dir for *.sls files and create an AutoSaltSLS object for each

Returns:int (count of sls objects found)

sls_objects_count

Return the count of sls objects

Returns:int

sls_sub_object_count

Return the count of child objects belonging to the top-level sls objects

Returns:int

top_files

Return the list of sls objects marked as top files

Returns:list

visible_sls_objects

Return a list of all sls objects that are not marked as ‘hidden’

Returns:list

write()

Generate the rst files for the loaded sls objects

class autosaltsls.mapper.AutoSaltSLSMapperSettings(app, source, settings)

Class to hold the source-level settings for a AutoSaltSLSMapper object.

autosaltsls.objects

Classes to describe AutoSaltAPI sls files as objects.

class autosaltsls.objects.AutoSaltSLS(app, basename, source_path, source_settings, parent_name=None, source_url_root=None)

Object representation of an sls file or directory.

app

Sphinx application instance

basename

sls filename or group name (e.g. ‘ssl_enabled.sls’ or ‘apache’)

source_path

Full path to the location of the expected sls file for this object

source_settings

AutoSaltSLSMapperSettings object for the source creating this instance

parent_name : None

Name of the parent group (e.g. for ‘ssl_enabled.sls’ this might be ‘apache’)

source_url_root: None

URL root to the source control viewable files location

add_child(child_obj)

Add a child AutoSaltSLS to this instance.

child_obj

An AutoSaltSLS instance

add_entry(entry)

Add an AutoSaltSLSEntry entry object to this instance. If the entry is a step append it to the list of steps instead.

entry

An AutoSaltSLSEntry instance

annotated_body

Return the debug annotated text output for all body entries with newline terminators.

Returns:str

body

Return the list of entries comprising the body (i.e. everything except the header).

Returns:list

body_text

Return all the text for the body entries as one string with newline terminators.

Returns:str

child_count

Return the number of children.

Returns:int

header

Return the first entry in the list or a dummy entry if there is no content.

Returns:AutoSaltSLSEntry

name

Return the full dot-separated name of the sls object (e.g. apache.sls_configured).

Returns:str

output_rst(jinja_env, output_dir, filename=None, template=None)

Generate the base rst file for this sls object.

jinja_env

Jinja Environment object to use when rendering templates

output_dir

Full path to the location for this file

filename : None

Filename to use for rst file, defaults to rst_filename property

template : None

Template file to use. Defaults to ‘top.rst_t’ for a topfile or ‘sls.rst_t’ otherwise

parse_file()

Read the associated sls file, create an AutoSaltSLSEntry object for any comment blocks found and add them as entries.

prefixed_name

Return the full dot-separated name of the sls object (e.g. apache.sls_configured) with the source-specific prefix applied.

Returns:str

set_initfile(rst_filename=None)

Shortcut function to set all the attributes needed for this object to be an init file.

text

Return all the entries including the header as a string with newline terminators.

Returns:str

toc_entry

Return the toctree entry for the top-level index file to use.

Returns:str

write_rst_files(jinja_env, build_root_dir)

Write the rst files for this object and all children.

jinja_env

Jinja Environment object to use when rendering templates

build_root_dir

Root dir for the source output files

Returns:int Count of files created

class autosaltsls.objects.AutoSaltSLSEntry(text=None)

Object representation of an sls file comment block. The data is logically split into a summary (all text to the first blank line) and content (the rest).

text : None

Initial text to place in lines

Directives

Directives are run-time changes to apply to an entry. They are specified on the document prefix line as a comma-separated list

environment

Use the following line as a topfile environment (e.g. ‘base’, ‘production’)

hidden

Do not generate documentation for this file, also sets ignore

ignore

Immediately stop processing the file. Any entries already found are returned as normal

include

The lines following this comment block will be an include: section and should be parsed to add the YAML list data items to the includes list

show_id

Read the first line following this comment block and add it as a content line

step

This comment block entry is to be added to the numbered list of steps

step_id

Read the first line following this comment block and add it as summary then add the entry to the numbered list of steps

summary_id

Read the first line following this comment block and add it as the entry summary

topfile_id

Read the first line following this comment block and add it as the entry summary then process the following

lines to extract the matching criteria and sub-lines for generating cross-references

add_include(include)

Add an include statement to the list and set the include property.

include

Include statement to add

annotated_text

Return an annotated output of the entry for inclusion in the sphinx debug output.

Returns:str

append_line(text)

Append some text to the content lines.

text

Text to append to the content lines

content

Return the content (i.e. everything after the first paragraph).

Returns:str

has_text

Return flag to say if the entry has any text stored.

Returns:bool

is_step

Return whether the entry is a step or not.

Returns:bool

prepend_id

Return whether this entry should prepend the YAML id to the output

Returns:bool

prepend_line(text)

Add some text to the start of the content line list.

text

Text to add to the start of the content lines

process_id(new_val=None)

Flag to show whether this entry requires YAML id processing. If not set and no new_val supplied, then the flag value is calculated based on other directive attributes.

Returns:bool

summary

Return the first paragraph (i.e. down to the first blank line) of the content lines as the summary.

Returns:str

text

Return all the stored lines as a string joined with newline terminators.

Returns:str