1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
|Build Status| |codecov| |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
.. |codecov| image:: https://codecov.io/gh/adamtheturtle/sphinx-substitution-extensions/branch/main/graph/badge.svg
:target: https://codecov.io/gh/adamtheturtle/sphinx-substitution-extensions
.. |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
|
