Repository files navigation

Extensions for Sphinx which allow substitutions within code blocks.

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

$pip install Sphinx-Substitution-Extensions

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

"""Configuration for Sphinx."""extensions= ["sphinxcontrib.spelling"]# Example existing extensionsextensions+= ["sphinx_substitution_extensions"]

2. Set the following variable inconf.py to define substitutions:

"""Configuration for Sphinx."""rst_prolog=""".. |release| replace:: 0.1.. |author| replace:: Eleanor"""

This will replace|release| in the new directives with0.1, and|author| withEleanor.

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

..code-block::shell   :substitutions:echo"|author| released version |release|"

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

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

This adds:content-substitutions: and:path-substitutions: options to Sphinx's built-inliteralinclude directive.

Replace substitutions in the content of the included file:

..literalinclude::path/to/file.txt:content-substitutions:

Replace substitutions in the file path:

..literalinclude::path/to/|author|_file.txt:path-substitutions:

This adds a:path-substitutions: option to Sphinx's built-inimage directive.

Replace substitutions in the image path:

..image::path/to/|author|_diagram.png:path-substitutions::alt:Diagram

1. Addsphinx_substitution_extensions toextensions inconf.py to enable the extension:

"""Configuration for Sphinx."""extensions= ["myst_parser"]# Example existing extensionsextensions+= ["sphinx_substitution_extensions"]

2. Set the following variables inconf.py to define substitutions:

"""Configuration for Sphinx."""myst_enable_extensions= ["substitution"]myst_substitutions= {"release":"0.1","author":"Eleanor",}

This will replace|release| in the new directives with0.1, and|author| withEleanor.

By default, you need to explicitly add the:substitutions: flag tocode-block directives, and:content-substitutions: or:path-substitutions: flags toliteralinclude directives.

If you want substitutions to be applied by default without needing these flags, you can set the following inconf.py:

"""Configuration for Sphinx."""substitutions_default_enabled=True

When this is enabled:

• Allcode-block directives will have substitutions applied automatically
• Allliteralinclude directives will have both content and path substitutions applied automatically

You can disable substitutions for specific directives when the default is enabled:

..code-block::shell   :nosubstitutions:echo"This |will| not be substituted"..literalinclude::path/to/file.txt:nocontent-substitutions:..literalinclude::path/to/|literal|_file.txt:nopath-substitutions:

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

```{code-block} bash   :substitutions:   echo "|author| released version |release|"```

As well as using|author|, you can also use{{author}}.This will respect the value ofmyst_sub_delimiters as set inconf.py.

{substitution-code}`echo "|author| released version |release|"`

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

This adds:content-substitutions: and:path-substitutions: options to Sphinx's built-inliteralinclude directive.

Replace substitutions in the content of the included file:

```{literalinclude} path/to/file.txt   :content-substitutions:```

Replace substitutions in the file path:

```{literalinclude} path/to/|author|_file.txt   :path-substitutions:```

This adds a:path-substitutions: option to Sphinx's built-inimage directive.

Replace substitutions in the image path:

```{image} path/to/|author|_diagram.png   :path-substitutions:   :alt: Diagram```

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.

SeeCONTRIBUTING.rst.