|Build Status| |PyPI|
Sphinx Substitution Extensions
==============================
Extensions for Sphinx which allow substitutions within code blocks.
.. contents::
Installation
------------
Sphinx Substitution Extensions is compatible with Sphinx 8.2.0+ using Python |minimum-python-version|\+.
.. code-block:: console
$ pip install Sphinx-Substitution-Extensions
rST setup
---------
1. Add the following to ``conf.py`` to enable the extension:
.. code-block:: python
"""Configuration for Sphinx."""
extensions = ["sphinxcontrib.spelling"] # Example existing extensions
extensions += ["sphinx_substitution_extensions"]
2. Set the following variable in ``conf.py`` to define substitutions:
.. code-block:: python
"""Configuration for Sphinx."""
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:: rst
.. code-block:: shell
:substitutions:
echo "|author| released version |release|"
Inline ``:substitution-code:``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: rst
:substitution-code:`echo "|author| released version |release|"`
``substitution-download``
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: rst
:substitution-download:`|author|'s manuscript <|author|_manuscript.txt>`
MyST Markdown setup
-------------------
1. Add ``sphinx_substitution_extensions`` to ``extensions`` in ``conf.py`` to enable the extension:
.. code-block:: python
"""Configuration for Sphinx."""
extensions = ["myst_parser"] # Example existing extensions
extensions += ["sphinx_substitution_extensions"]
2. Set the following variables in ``conf.py`` to define substitutions:
.. code-block:: python
"""Configuration for Sphinx."""
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:: markdown
```{code-block} bash
:substitutions:
echo "|author| released version |release|"
```
As well as using ``|author|``, you can also use ``{{author}}``.
This will respect the value of ``myst_sub_delimiters`` as set in ``conf.py``.
Inline ``:substitution-code:``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: rst
{substitution-code}`echo "|author| released version |release|"`
``substitution-download``
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: rst
{substitution-download}`|author|'s manuscript <|author|_manuscript.txt>`
Credits
-------
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 <./CONTRIBUTING.rst>`_.
.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-substitution-extensions/actions/workflows/ci.yml/badge.svg?branch=main
:target: https://github.com/adamtheturtle/sphinx-substitution-extensions/actions
.. _code-block: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
.. |PyPI| image:: https://badge.fury.io/py/Sphinx-Substitution-Extensions.svg
:target: https://badge.fury.io/py/Sphinx-Substitution-Extensions
.. |minimum-python-version| replace:: 3.10
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-substitution-extensions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "documentation, rst, sphinx",
"author": null,
"author_email": "Adam Dangoor <adamdangoor@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/6c/3a57f3efbda1733fa36c3a441028b98510cf304c82f7bd603704a9b49ba1/sphinx_substitution_extensions-2025.10.24.tar.gz",
"platform": null,
"description": "|Build Status| |PyPI|\n\nSphinx Substitution Extensions\n==============================\n\nExtensions for Sphinx which allow substitutions within code blocks.\n\n.. contents::\n\nInstallation\n------------\n\nSphinx Substitution Extensions is compatible with Sphinx 8.2.0+ using Python |minimum-python-version|\\+.\n\n.. code-block:: console\n\n $ pip install Sphinx-Substitution-Extensions\n\nrST setup\n---------\n\n1. Add the following to ``conf.py`` to enable the extension:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n extensions = [\"sphinxcontrib.spelling\"] # Example existing extensions\n\n extensions += [\"sphinx_substitution_extensions\"]\n\n2. Set the following variable in ``conf.py`` to define substitutions:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n rst_prolog = \"\"\"\n .. |release| replace:: 0.1\n .. |author| replace:: Eleanor\n \"\"\"\n\nThis will replace ``|release|`` in the new directives with ``0.1``, and ``|author|`` with ``Eleanor``.\n\nUsing substitutions in rST documents\n------------------------------------\n\n``code-block``\n~~~~~~~~~~~~~~\n\nThis adds a ``:substitutions:`` option to Sphinx's built-in `code-block`_ directive.\n\n.. code-block:: rst\n\n .. code-block:: shell\n :substitutions:\n\n echo \"|author| released version |release|\"\n\nInline ``:substitution-code:``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: rst\n\n :substitution-code:`echo \"|author| released version |release|\"`\n\n``substitution-download``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: rst\n\n :substitution-download:`|author|'s manuscript <|author|_manuscript.txt>`\n\n\nMyST Markdown setup\n-------------------\n\n1. Add ``sphinx_substitution_extensions`` to ``extensions`` in ``conf.py`` to enable the extension:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n extensions = [\"myst_parser\"] # Example existing extensions\n\n extensions += [\"sphinx_substitution_extensions\"]\n\n2. Set the following variables in ``conf.py`` to define substitutions:\n\n.. code-block:: python\n\n \"\"\"Configuration for Sphinx.\"\"\"\n\n myst_enable_extensions = [\"substitution\"]\n\n myst_substitutions = {\n \"release\": \"0.1\",\n \"author\": \"Eleanor\",\n }\n\nThis will replace ``|release|`` in the new directives with ``0.1``, and ``|author|`` with ``Eleanor``.\n\nUsing substitutions in MyST Markdown\n------------------------------------\n\n``code-block``\n~~~~~~~~~~~~~~\n\nThis adds a ``:substitutions:`` option to Sphinx's built-in `code-block`_ directive.\n\n.. code-block:: markdown\n\n ```{code-block} bash\n :substitutions:\n\n echo \"|author| released version |release|\"\n ```\n\nAs well as using ``|author|``, you can also use ``{{author}}``.\nThis will respect the value of ``myst_sub_delimiters`` as set in ``conf.py``.\n\nInline ``:substitution-code:``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: rst\n\n {substitution-code}`echo \"|author| released version |release|\"`\n\n``substitution-download``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: rst\n\n {substitution-download}`|author|'s manuscript <|author|_manuscript.txt>`\n\nCredits\n-------\n\nClusterHQ Developers\n~~~~~~~~~~~~~~~~~~~~\n\nThis package is largely inspired by code written for Flocker by ClusterHQ.\nDevelopers of the relevant code include, at least, Jon Giddy and Tom Prince.\n\nContributing\n------------\n\nSee `CONTRIBUTING.rst <./CONTRIBUTING.rst>`_.\n\n.. |Build Status| image:: https://github.com/adamtheturtle/sphinx-substitution-extensions/actions/workflows/ci.yml/badge.svg?branch=main\n :target: https://github.com/adamtheturtle/sphinx-substitution-extensions/actions\n.. _code-block: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block\n.. |PyPI| image:: https://badge.fury.io/py/Sphinx-Substitution-Extensions.svg\n :target: https://badge.fury.io/py/Sphinx-Substitution-Extensions\n.. |minimum-python-version| replace:: 3.10\n",
"bugtrack_url": null,
"license": null,
"summary": "Extensions for Sphinx which allow for substitutions.",
"version": "2025.10.24",
"project_urls": {
"Source": "https://github.com/adamtheturtle/sphinx-substitution-extensions"
},
"split_keywords": [
"documentation",
" rst",
" sphinx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f9d404f1540dd78a140813ed56cfd8a18f4bdda1c77438712c20903348f622d3",
"md5": "c826171ba72970af95a6ac67ae3448f1",
"sha256": "243619a13616566be8f00fa75e5f946116ec53dd6dc30ff837d62b53bdbee95f"
},
"downloads": -1,
"filename": "sphinx_substitution_extensions-2025.10.24-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c826171ba72970af95a6ac67ae3448f1",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 7332,
"upload_time": "2025-10-24T08:53:39",
"upload_time_iso_8601": "2025-10-24T08:53:39.200183Z",
"url": "https://files.pythonhosted.org/packages/f9/d4/04f1540dd78a140813ed56cfd8a18f4bdda1c77438712c20903348f622d3/sphinx_substitution_extensions-2025.10.24-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb6c3a57f3efbda1733fa36c3a441028b98510cf304c82f7bd603704a9b49ba1",
"md5": "66cff93ca460c09db90a65be25a2c75a",
"sha256": "95f9fd2fed1a11809191c31340b13ab9ad41df6e29b1567b8da28897725a803a"
},
"downloads": -1,
"filename": "sphinx_substitution_extensions-2025.10.24.tar.gz",
"has_sig": false,
"md5_digest": "66cff93ca460c09db90a65be25a2c75a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21143,
"upload_time": "2025-10-24T08:53:40",
"upload_time_iso_8601": "2025-10-24T08:53:40.437564Z",
"url": "https://files.pythonhosted.org/packages/eb/6c/3a57f3efbda1733fa36c3a441028b98510cf304c82f7bd603704a9b49ba1/sphinx_substitution_extensions-2025.10.24.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 08:53:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamtheturtle",
"github_project": "sphinx-substitution-extensions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-substitution-extensions"
}
JSON
