pombredanne / sphinx-substitution-extensions

Extensions for Sphinx which allow substitutions

Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions.

Contents

• Sphinx Substitution Extensions
  • Installation
    • Setup
  • Directives
    • code-block
    • prompt
    • Inline :substitution-code:
  • Credits
    • sphinx-prompt authors
    • ClusterHQ Developers
  • Contributing

Installation

$ pip install Sphinx-Substitution-Extensions

This supports Python 3.8+.

Setup

• Add the following to conf.py:

# sphinx-prompt must be the first of these two.
extensions += ['sphinx-prompt', 'sphinx_substitution_extensions']

• Set the following variable in conf.py:

rst_prolog = """
.. |release| replace:: 0.1
.. |author| replace:: Eleanor
"""

This will replace |release| in the new directives with 0.1, and |author| with Eleanor.

Directives

code-block

This adds a :substitutions: option to Sphinx's built-in code-block directive.

.. code-block:: bash
   :substitutions:

   echo "|author| released version |release|"

prompt

This adds a :substitutions: option to sphinx-prompt.

.. prompt:: bash
   :substitutions:

   echo "|author| released version |release|"

Inline :substitution-code:

:substitution-code:`echo "|author| released version |release|"`

Credits

sphinx-prompt authors

Thanks to @sbrunner and other contributors for sphinx-prompt. substitution-prompt is based on sphinx-prompt.

ClusterHQ Developers

This package is largely inspired by code written for Flocker by ClusterHQ. Developers of the relevant code include, at least, Jon Giddy and Tom Prince.

Contributing

See CONTRIBUTING.rst.