Glossary

Directive

Directives are special commands that can be embedded as text into an rST document. They can be used to dictate how content in the document gets formatted by Sphinx.

For example this:

.. admonition:: title

    content

… would generate this:

title

content

For more information, see Sphinx’s Directive documentation

Index

An index is an rST file used to indicate the layout of documents. It contains at least one toctree.

One index of note is the Root Index

rST

reStructuredText is a plaintext markup language that Sphinx can use to generate documentation. This will be the standard way we write documentation in this project. Mardown is an alternative langauge.

See this cheat sheet for the common markup used in rST files.

Root Index

The root index is the top-level Index rooted in the docs/ folder located in your project. This index contains a toctree that specifies the tabs in the top navigation bar.

Role

A role is a type of annotation used in rST documents to indicate special formatting. Roles can be used inline with text. For example, :code:`text` would evaluate to text.

Sphinx has some built-in roles. Extensions can also add new roles. For example, sphinx-design adds roles for in-line badges and icons like this: .

A Directive can also have roles associated with it, in which case they work as “options” or “parameters”. For example, to add line numbers to a code block directive, you need to add the :linenos: option below the declaration:

.. code-block::
    :linenos:

    Example

toctree

toctree (Table of Contents Tree) is a kind of directive that is used to specify how documents should be laid out. Here’s an example of the root index:

.. toctree::
    :maxdepth: 1

    guides/index
    tab_2/index
    tab_3/index