Skip to main content

Extensions for Sphinx which allow for substitutions.

Project description

Build Status codecov PyPI

Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions within code blocks.


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

$ pip install Sphinx-Substitution-Extensions


  1. Add the following to

extensions += ['sphinx_substitution_extensions']
  1. Set the following variable in

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 should look like:

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



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

.. code-block:: bash

   echo "|author| released version |release|"


This adds a :substitutions: option to sphinx-prompt.

.. prompt:: bash

   echo "|author| released version |release|"

Inline :substitution-code:

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


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.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Sphinx Substitution Extensions-2022.2.16.tar.gz (18.7 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page