[ Sending this to #932957 as well, as it contains valueable info on that topic ]
Jeremy Stanley <fu...@yuggoth.org> wrote (Wed, 24 May 2023 18:22:09 +0000): > On 2023-05-24 19:40:56 +0200 (+0200), Agathe Porte wrote: > [...] > > Maybe the idea was to introduce %OLD_RELEASE_NAME% and to call sed to > > replace this kind of strings in a build step, and not rely on sphinx > > substitution at all. > > > > I know that I have done this a few times and it works fine as a very > > simple preprocessor. > > Similar things can be done at sphinx-build time with a custom Sphinx > extension (can be a trivial Python module). We do that for the > published security advisories list upstream in OpenStack: > > https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/conf.py#L31 > > https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/_exts/vmt.py > > That's a more complex example because we generate a ton of content > out of structured data (YAML) files by splatting the relevant fields > into substitutions in a Jinja2 template, but for basic string > substitution you could get away with something far simpler, or even > use a canned one like (this was simply my first web search result): > > https://pypi.org/project/Sphinx-Substitution-Extensions/ > > The examples in its readme look to be along the lines of the Debian > Release Notes use case anyway. There's also basic substitutions > support in the reStructuredText specification, which might be useful > to reduce the amount of actual content you need to swap at build > time: > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions The above seem related to the issue in question, but the solution pointed out by James Addison in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932957#90 (use parsed-literal ('.. parsed-literal::') blocks) seems to be the easier one (at least for this document) and it works fine here. So I would go for it. Thanks anyway Holger -- Holger Wansing <hwans...@mailbox.org> PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
