adamtheturtle / sphinx-substitution-extensions

Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions within code blocks.

Installation

Sphinx Substitution Extensions is compatible with Sphinx 4.0+ using Python 3.8+.

$ pip install Sphinx-Substitution-Extensions

Setup

1. Add the following to conf.py:

extensions += ['sphinx_substitution_extensions']

2. 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.

Optional: sphinx-prompt

Sphinx Substitution Extensions supports the third-party extension sphinx-prompt.

1. If you don't have sphinx-prompt installed, you can include the extension with the extra dependency prompt:

$ pip install Sphinx-Substitution-Extensions[prompt]

2. Make sure sphinx-prompt dependency is loaded before sphinx_substitution_extensions. For example, your conf.py should look like:

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

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.