Extensions for Sphinx which allow substitutions within code blocks.
Contents
Sphinx Substitution Extensions is compatible with Sphinx 8.2.0+ using Python 3.10+.
$ pip install Sphinx-Substitution-Extensions- Add the following to
conf.pyto enable the extension:
"""Configuration for Sphinx."""
extensions = ["sphinxcontrib.spelling"] # Example existing extensions
extensions += ["sphinx_substitution_extensions"]- Set the following variable in
conf.pyto 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>`This adds :content-substitutions: and :path-substitutions: options to Sphinx's built-in literalinclude directive.
Replace substitutions in the content of the included file:
.. literalinclude:: path/to/file.txt
:content-substitutions:Replace substitutions in the file path:
.. literalinclude:: path/to/|author|_file.txt
:path-substitutions:This adds a :path-substitutions: option to Sphinx's built-in image directive.
Replace substitutions in the image path:
.. image:: path/to/|author|_diagram.png
:path-substitutions:
:alt: Diagram- Add
sphinx_substitution_extensionstoextensionsinconf.pyto enable the extension:
"""Configuration for Sphinx."""
extensions = ["myst_parser"] # Example existing extensions
extensions += ["sphinx_substitution_extensions"]- Set the following variables in
conf.pyto 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.
By default, you need to explicitly add the :substitutions: flag to code-block directives, and :content-substitutions: or :path-substitutions: flags to literalinclude directives.
If you want substitutions to be applied by default without needing these flags, you can set the following in conf.py:
"""Configuration for Sphinx."""
substitutions_default_enabled = TrueWhen this is enabled:
- All
code-blockdirectives will have substitutions applied automatically - All
literalincludedirectives will have both content and path substitutions applied automatically
You can disable substitutions for specific directives when the default is enabled:
.. code-block:: shell
:nosubstitutions:
echo "This |will| not be substituted"
.. literalinclude:: path/to/file.txt
:nocontent-substitutions:
.. literalinclude:: path/to/|literal|_file.txt
:nopath-substitutions: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.
{substitution-code}`echo "|author| released version |release|"`{substitution-download}`|author|'s manuscript <|author|_manuscript.txt>`This adds :content-substitutions: and :path-substitutions: options to Sphinx's built-in literalinclude directive.
Replace substitutions in the content of the included file:
```{literalinclude} path/to/file.txt
:content-substitutions:
```Replace substitutions in the file path:
```{literalinclude} path/to/|author|_file.txt
:path-substitutions:
```This adds a :path-substitutions: option to Sphinx's built-in image directive.
Replace substitutions in the image path:
```{image} path/to/|author|_diagram.png
:path-substitutions:
:alt: Diagram
```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.