Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions within code blocks.

Contents

• Sphinx Substitution Extensions
  • Installation
  • rST setup
  • Using substitutions in rST documents
    • code-block
    • Inline :substitution-code:
    • substitution-download
  • MyST Markdown setup
  • Using substitutions in MyST Markdown
    • code-block
  • Credits
    • ClusterHQ Developers
  • Contributing

Installation

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

$ pip install Sphinx-Substitution-Extensions

rST setup

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

extensions += ['sphinx_substitution_extensions']

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

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

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

Using substitutions in rST documents

code-block

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

.. code-block:: bash
   :substitutions:

   echo "|author| released version |release|"

Inline :substitution-code:

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

substitution-download

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

MyST Markdown setup

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

extensions += ['sphinx_substitution_extensions']

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

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.

Using substitutions in MyST Markdown

code-block

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

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

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

Credits

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.