Bug#932957: #932957 Please migrate Release Notes to reStructuredText
[ Sending this to #932957 as well, as it contains valueable info on that topic ]
Jeremy Stanley <fungi@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 <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Reply to: