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.

Installation

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

$ pip install Sphinx-Substitution-Extensions

Setup

  1. Add the following to conf.py:
extensions += ['sphinx_substitution_extensions']
  1. Set the following variable in conf.py:
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 conf.py should look like:

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

Directives

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.

Note

Requires the extension sphinx-prompt.

.. prompt:: bash
   :substitutions:

   echo "|author| released version |release|"

Inline :substitution-code:

:substitution-code:`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.

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 Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page