Support passing replacements to the "include" directive

[tzach]

Thanks for a great extension.

In many cases, I combine include and replacement as follow

upgrade.4.0-to-4.1.rst

.. |SRC_VERSION| replace:: 4.0
.. |NEW_VERSION| replace:: 4.1
.. include:: /upgrade/_common/upgrade-guide-v2-rpm.rst

upgrade.4.1-to-4.2.rst

.. |SRC_VERSION| replace:: 4.1
.. |NEW_VERSION| replace:: 4.2
.. include:: /upgrade/_common/upgrade-guide-v2-rpm.rst

sphinx-substitution-extensions is great because it allows me to replace in code blocks, but having all the replacement rules in conf.py does not allow it to ve use in the above example.

[adamtheturtle]

This extension allows replacements to be defined in the .rst document. However it will not replace text in an include directive, which I think is what you are trying to do. This issue is still valid but probably involves adding a :substitutions: option to the .. include directive.

[tzach]

This extension allows replacements to be defined in the .rst document.

How can I do that?

This issue is still valid but probably involves adding a :substitutions: option to the .. include directive.

Thanks, please consider this a feature request

[adamtheturtle]

This extension allows replacements to be defined in the .rst document.

@tzach I mean, with the code-block and others, if you use replacements in the .rst document, it works.

Thanks, please consider this a feature request

Done!

I will say that I am a little overwhelmed right now with work and so this is not my top priority. I would be happy to review a PR or even pair a little.

[jhermann]

Another directive that could profit from a :substitutions: parameter is toctree, my use-case is including generated API docs that have the package name in their path.

[adamtheturtle]

Sounds good @jhermann . I'm happy to look at that when I next have time for this project.

[adamtheturtle]

@jhermann If you could provide a little sample for me to see what is not substituted, that might help this go faster.

[jhermann]

See https://github.com/Springerle/py-generic-project/blob/master/%7B%7Bcookiecutter.repo_name%7D%7D/docs/api-reference.rst and imagine the replacement not done by Jinja2 / Cookiecutter, but instead at runtime by the extension.

[adamtheturtle]

I hadn't considered generated doc paths. It makes me think for the .. include directive, does one maybe want substitution for the included file path? Or just the contents of the file?

[jhermann]

Well, I have no concrete example, but it is certainly thinkable. OK, I have a maybe contrived one, imagine you want OS-specific versions of a manual, and include dynamic texts per OS -- could use sphinx.ext.ifconfig, but simple include directives would seem less bulky.

[adamtheturtle]

Like literalinclude we can use separate options for replacements in contents and replacements in paths. For doc8 support, we will have to add an exception to Include directive - https://github.com/PyCQA/doc8/blob/e4d2539177a3d72c8e52d91708bbe62e5085155d/src/doc8/checks.py.