Terminology

reStructuredText (.rst)

reStructuredText is the default plaintext markup language used by Sphinx.

Sphinx extension

A Sphinx extension is a Python package that provides roles and directives. They are use to intepret part of .rst file.

Role

A role is invoked when processing a command inline.

Some text with a :hello:`world` role.

Sphinx directive

A directive is invoked when processing a paragraph involved in a .rst file:

.. hello:: world

Optional parameters

A directive may support optional parameters depending on its specifications:

.. hello:: world
    :param1:
    :param2:
    :param3: some value

     some content

The specifications are class attributes of the class implementing the Sphinx directive. See this tutorial.

Configuration

A directive may be configured from the docs/conf.py Sphinx configuration file (see the configuration section).