CODEWITHSUNDEEP
pythonversioningpython-sphinxsubstitutionrestructuredtext
Boni García
Boni García

Reputation: 4858

Variable substitution not working properly in Sphinx

I have a documentation project made with Sphinx. I am using global variables by means of the configuration key rst_epilog. My conf.py file contains the following:

rst_epilog = """
.. |MY_VERSION| replace:: 2.1.0
"""

Then, in a rst page, I'm using the formerly defined variable (VERSION) as follows:

The version of my repo is: |MY_VERSION|

.. sourcecode:: bash

    git clone https://github.com/my-organization/my-repo.git
    cd my-repo
    git checkout |MY_VERSION|

After building the documentation, in the resulting HTML, the first variable is correctly substituted, but not the second: enter image description here

Clearly the substitution does not work inside formatted source code blocks, which is very inconvenient.

Is it possible to workaround this issue?

PS: I also tried with rst_prolog with the same result.

Upvotes: 2

Views: 2786

Answers (2)

Adam Dangoor
Adam Dangoor

Reputation: 436

I have created a Sphinx extension which provides substitution-code-block for this purpose.

It allows you to define substitutions in conf.py and then use these substitutions in .. substitution-code-block blocks.

This extension is at https://github.com/adamtheturtle/sphinx-substitution-extensions.

However, this is a very small amount of code. To enable this in your own codebase without a third party extension, create a module in your codebase with the following contents:

"""
Custom Sphinx extensions.
"""

from typing import List

from sphinx.application import Sphinx
from sphinx.directives.code import CodeBlock


class SubstitutionCodeBlock(CodeBlock):  # type: ignore
    """
    Similar to CodeBlock but replaces placeholders with variables.
    """

    def run(self) -> List:
        """
        Replace placeholders with given variables.
        """
        app = self.state.document.settings.env.app
        new_content = []
        self.content = self.content  # type: List[str]
        existing_content = self.content
        for item in existing_content:
            for pair in app.config.substitutions:
                original, replacement = pair
                item = item.replace(original, replacement)
            new_content.append(item)

        self.content = new_content
        return list(CodeBlock.run(self))


def setup(app: Sphinx) -> None:
    """
    Add the custom directives to Sphinx.
    """
    app.add_config_value('substitutions', [], 'html')
    app.add_directive('substitution-code-block', SubstitutionCodeBlock)

Then, use this module the extensions defined in conf.py. Then, set the substitutions variable in conf.py e.g. to [('|foo|', 'bar')] to replace |foo| with bar in every substitution-code-block.

Upvotes: 3

mzjn
mzjn

Reputation: 50947

This will make the substitution work:

.. parsed-literal::

   git clone https://github.com/my-organization/my-repo.git
   cd my-repo
   git checkout |MY_VERSION|

With the parsed-literal directive, you can have substitutions (and other inline markup) but there is no syntax highlighting.

With code-block (orsourcecode, or highlight), you can have syntax highlighting but inline markup is not processed.

Upvotes: 4

Related Questions