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 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']
  1. 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']
  1. 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.

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-2024.2.25.tar.gz (25.4 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