Extensions for Sphinx which allow substitutions within code blocks.

Sphinx Substitution Extensions is compatible with Sphinx 7.2.0+ using Python 3.10+.

$ pip install Sphinx-Substitution-Extensions

1. Add the following to conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["sphinxcontrib.spelling"]  # Example existing extensions

extensions += ["sphinx_substitution_extensions"]

2. Set the following variable in conf.py to define substitutions:

"""Configuration for Sphinx."""

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

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

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

.. code-block:: shell
   :substitutions:

   echo "|author| released version |release|"

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

:substitution-download:`|author|'s manuscript <|author|_manuscript.txt>`

1. Add sphinx_substitution_extensions to extensions in conf.py to enable the extension:

"""Configuration for Sphinx."""

extensions = ["myst_parser"]  # Example existing extensions

extensions += ["sphinx_substitution_extensions"]

2. Set the following variables in conf.py to define substitutions:

"""Configuration for Sphinx."""

myst_enable_extensions = ["substitution"]

myst_substitutions = {
    "release": "0.1",
    "author": "Eleanor",
}

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

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

```{code-block} bash
   :substitutions:

   echo "|author| released version |release|"
```

As well as using |author|, you can also use {{author}}. This will respect the value of myst_sub_delimiters as set in conf.py.

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.

See CONTRIBUTING.rst.