adamtheturtle / sphinx-substitution-extensions

Extensions for Sphinx which allow substitutions

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
    • prompt
    • Inline :substitution-code:
    • substitution-download
  • MyST Markdown setup
  • Using substitutions in MyST Markdown
    • code-block
  • Credits
    • sphinx-prompt authors
    • 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|"

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|"`

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

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.