Writing documentation

Your project’s documentation is located in the docs directory.

Markup language

docs/*

You can write dedicated documentation pages using either MyST (a Markdown superset) or reStructuredText (rST). Mixing files of different formats is allowed.

Docstrings

Docstrings in your modules must be written in rST.

Tagging changes between versions

Document any user-facing changes between releases using the versionadded, versionchanged, deprecated, or versionremoved directives.

changed_arg
:   Has been doing something for a long time.

    :::{versionchanged} 1.1.0
    Does it a little differently now.
    :::

new_arg
:   Does something new.

    :::{versionadded} 1.1.0
    :::

changed_arg
    Has been doing something for a long time.

    ..versionchanged:: 1.1.0
        Does it a little differently now.

new_arg
    Does something new.

    .. versionadded:: 1.1.0
changed_arg

Has been doing something for a long time.

Changed in version 1.1.0: Does it a little differently now.

new_arg

Does something new.

Added in version 1.1.0.

Cross-references

Entities

Improve documentation usability by cross-referencing entities. Some highlights:

Modules

Link to a complete module.

{py:mod}`foo <saltext.foo.modules.foo_mod>`

:py:mod:`foo <saltext.foo.modules.foo_mod>`

Hint

Works for all packages registered in the docs/conf.py intersphinx_mapping. This specifically includes Salt core by default.

Functions

Link to a specific function within a module.

{py:func}`foo.bar <saltext.foo.modules.foo_mod.bar>`

:py:func:`foo.bar <saltext.foo.modules.foo_mod.bar>`

Hint

Works for all packages registered in the docs/conf.py intersphinx_mapping. This specifically includes Salt core by default.

Salt master configuration

Link to the documentation of a Salt master configuration value.

{conf_master}`ssh_minion_opts`

:conf_master:`ssh_minion_opts`

Salt minion configuration

Link to the documentation of a Salt minion configuration value.

{conf_minion}`order_masters`

:conf_minion:`order_masters`

Arbitrary anchors

Define and reference custom anchors within the same or different documents.

(my-custom-target)=
# Something

...

Later in the file, or in another one:

Please refer to [Something](my-custom-target)

.. _my-custom-target:
Something
=========

...

Later in the file, or in another one:

Please refer to :ref:`Something <my-custom-target>`

Admonitions

Use admonitions to add notes or emphasize important information.

:::{important}
Ensure you understand the usage of admonitions.
:::

.. important::
    Ensure you understand the usage of admonitions.

Important

Ensure you understand the usage of admonitions.

Common admonitions include:

  • important

  • hint

  • note

  • warning

  • attention

  • tip

Tabs

You can use tabs to organize content, as shown here. Tabs with the same titles will synchronize.

:::{tab} MyST
... is a supserset of Markdown.
:::

:::{tab} rST
... is not a supserset of Markdown.
:::

.. tab:: MyST
    ... is a supserset of Markdown.

.. tab:: RST
    ... is not a supserset of Markdown.