Writing Salt Documentation¶

Point-of-view¶

Use third-person perspective and avoid "I", "we", "you" forms of address. Identify the addressee specifically e.g., "users should", "the compiler does", etc.

Active voice¶

Use active voice and present-tense. Avoid filler words.

Title capitalization¶

Document titles and section titles within a page should follow normal sentence capitalization rules. Words that are capitalized as part of a regular sentence should be capitalized in a title and otherwise left as lowercase. Punctuation can be omitted unless it aids the intent of the title (e.g., exclamation points or question marks).

For example:

This is a main heading
======================

Paragraph.

This is an exciting sub-heading!
--------------------------------

Paragraph.

Serial Commas¶

According to Wikipedia: In English punctuation, a serial comma or series comma (also called Oxford comma and Harvard comma) is a comma placed immediately before the coordinating conjunction (usually "and", "or", or "nor") in a series of three or more terms. For example, a list of three countries might be punctuated either as "France, Italy, and Spain" (with the serial comma), or as "France, Italy and Spain" (without the serial comma)."

When writing a list that includes three or more items, the serial comma should always be used.

Inline documentation¶

Python has special multi-line strings called docstrings as the first element in a function or class. These strings allow documentation to live alongside the code and can contain special formatting. For example:

def my_function(value):
    '''
    Upper-case the given value

    Usage:

    .. code-block:: python

        val = 'a string'
        new_val = myfunction(val)
        print(new_val) # 'A STRING'

    :param value: a string
    :return: a copy of ``value`` that has been upper-cased
    '''
    return value.upper()

Specify a release for additions or changes¶

New functions or changes to existing functions should include a marker that denotes what Salt release will be affected. For example:

def my_function(value):
    '''
    Upper-case the given value

    .. versionadded:: 2014.7.0

    <...snip...>
    '''
    return value.upper()

For changes to a function:

def my_function(value, strip=False):
    '''
    Upper-case the given value

    .. versionchanged:: 2016.3.0
        Added a flag to also strip whitespace from the string.

    <...snip...>
    '''
    if strip:
        return value.upper().strip()
    return value.upper()

Adding module documentation to the index¶

Each module type has an index listing all modules of that type. For example: execution modules, state modules, renderer modules. New modules must be added to the index manually.

1. Edit the file for the module type: execution modules, state modules, renderer modules, etc.
2. Add the new module to the alphebetized list.
3. Build the documentation which will generate an .rst file for the new module in the same directory as the index.rst.
4. Commit the changes to index.rst and the new .rst file and send a pull request.

Glossary entries¶

Link to glossary entries using the term role. A cross-reference should be added the first time a Salt-specific term is used in a document.

A common way to encapsulate master-side functionality is by writing a
custom :term:`Runner Function`. Custom Runner Functions are easy to write.

Index entries¶

Sphinx automatically generates many kinds of index entries, but it is occasionally useful to manually add items to the index.

One method is to use the index directive above the document or section that should appear in the index.

.. index:: ! Event, event bus, event system
    see: Reactor; Event

Another method is to use the index role inline with the text that should appear in the index. The index entry is created and the target text is left otherwise intact.

Information about the :index:`Salt Reactor`
-------------------------------------------

Paragraph.

Documents and sections¶

Each document should contain a unique top-level label of the form:

.. _my-page:

My page
=======

Paragraph.

Unique labels can be linked using the ref role. This allows cross-references to survive document renames or movement.

For more information see :ref:`my-page`.

Note, the :doc: role should not be used to link documents together.

Modules¶

Cross-references to Salt modules can be added using Sphinx's Python domain roles. For example, to create a link to the test.ping function:

A useful execution module to test active communication with a minion is the
:py:func:`test.ping <salt.modules.test.ping>` function.

Salt modules can be referenced as well:

The :py:mod:`test module <salt.modules.test>` contains many useful
functions for inspecting an active Salt connection.

The same syntax works for all modules types:

One of the workhorse state module functions in Salt is the
:py:func:`file.managed <salt.states.file.managed>` function.

Settings¶

Individual settings in the Salt Master or Salt Minion configuration files are cross-referenced using two custom roles, conf_master, and conf_minion.

The :conf_minion:`minion ID <id>` setting is a unique identifier for a
single minion.