How to use substitution definitions with code blocks?
I tried using substitution definitions together with code blocks in Sphinx documentation however it doesn't work. This is my ReST source code:
.. |foo| code-block:: python
foo = 1
|foo|
Sphinx throws the following errors:
/.../examples.rst:184: WARNING: Substitution definition "foo" empty or invalid.
.. |foo| code-block:: python
foo = 1
/.../examples.rst:193: ERROR: Undefined substitution referenced: "foo".
How can I make this example work?
Sphinx version: 1.5.5 (using Sphinx 1.6.2 the above error transforms into a warning).
python-sphinx restructuredtext
asked Jun 26 '17 at 13:43
a_guest
5,11821241
add a comment |
I tried using substitution definitions together with code blocks in Sphinx documentation however it doesn't work. This is my ReST source code:
.. |foo| code-block:: python
foo = 1
|foo|
Sphinx throws the following errors:
/.../examples.rst:184: WARNING: Substitution definition "foo" empty or invalid.
.. |foo| code-block:: python
foo = 1
/.../examples.rst:193: ERROR: Undefined substitution referenced: "foo".
How can I make this example work?
Sphinx version: 1.5.5 (using Sphinx 1.6.2 the above error transforms into a warning).
python-sphinx restructuredtext
asked Jun 26 '17 at 13:43
a_guest
5,11821241
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57
add a comment |
I tried using substitution definitions together with code blocks in Sphinx documentation however it doesn't work. This is my ReST source code:
.. |foo| code-block:: python
foo = 1
|foo|
Sphinx throws the following errors:
/.../examples.rst:184: WARNING: Substitution definition "foo" empty or invalid.
.. |foo| code-block:: python
foo = 1
/.../examples.rst:193: ERROR: Undefined substitution referenced: "foo".
How can I make this example work?
Sphinx version: 1.5.5 (using Sphinx 1.6.2 the above error transforms into a warning).
python-sphinx restructuredtext
asked Jun 26 '17 at 13:43
a_guest
5,11821241
I tried using substitution definitions together with code blocks in Sphinx documentation however it doesn't work. This is my ReST source code:
.. |foo| code-block:: python
foo = 1
|foo|
Sphinx throws the following errors:
/.../examples.rst:184: WARNING: Substitution definition "foo" empty or invalid.
.. |foo| code-block:: python
foo = 1
/.../examples.rst:193: ERROR: Undefined substitution referenced: "foo".
How can I make this example work?
Sphinx version: 1.5.5 (using Sphinx 1.6.2 the above error transforms into a warning).
python-sphinx restructuredtext
python-sphinx restructuredtext
asked Jun 26 '17 at 13:43
a_guest
5,11821241
asked Jun 26 '17 at 13:43
a_guest
5,11821241
asked Jun 26 '17 at 13:43
a_guest
5,11821241
asked Jun 26 '17 at 13:43
a_guest
5,11821241
asked Jun 26 '17 at 13:43
a_guest
5,11821241
5,11821241
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57
add a comment |
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57
add a comment |
1 Answer
1
active
oldest
votes
This is not possible without changing code-block.
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.
answered Nov 12 at 17:40
Adam Dangoor
362
add a comment |
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f44761197%2fhow-to-use-substitution-definitions-with-code-blocks%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
1 Answer
1
active
oldest
votes
1 Answer
1
active
oldest
votes
active
oldest
votes
active
oldest
votes
This is not possible without changing code-block.
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.
answered Nov 12 at 17:40
Adam Dangoor
362
add a comment |
This is not possible without changing code-block.
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.
answered Nov 12 at 17:40
Adam Dangoor
362
add a comment |
This is not possible without changing code-block.
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.
answered Nov 12 at 17:40
Adam Dangoor
362
This is not possible without changing code-block.
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.
answered Nov 12 at 17:40
Adam Dangoor
362
answered Nov 12 at 17:40
Adam Dangoor
362
answered Nov 12 at 17:40
Adam Dangoor
362
answered Nov 12 at 17:40
Adam Dangoor
362
362
add a comment |
add a comment |
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Some of your past answers have not been well-received, and you're in danger of being blocked from answering.
Please pay close attention to the following guidance:
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f44761197%2fhow-to-use-substitution-definitions-with-code-blocks%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Very similar to stackoverflow.com/q/8789408/407651
– mzjn
Jun 26 '17 at 14:57