Bug#1064575: python-pyswarms-doc: please make the build reproducible.

[James Addison]

Followup-For: Bug #1064575

On Mon, 26 Feb 2024 00:22:44 +0000, I wrote:
> On Sat, 24 Feb 2024 12:33:50 +0000, I wrote:
> > Part of the documentation rendering process - I have not determined exactly
> > what yet - adds an 'alt' attribute when it does not exist, and generates a
> > randomized hex string to use as the value of the attribute.  This causes the
> > resulting python-pyswarms-doc package to vary on each build.
>
> Part of the reason for this appears to be the nbsphinx component; when it
> encounters HTML <img> elements, it emits reStructuredText markdown containing
> an alt attribute if one was found on the element, and defines an rST
> substitution[1] named by a UUID4-generated value converted to hexadecimal.
>
> Next question: where is that substitution name used when the ':alt:' option
> is not found on the image directive?

The answer is that the alt attribute/option is created by docutils here:

  https://sources.debian.org/src/python-docutils/0.20.1%2Bdfsg-3/docutils/parsers/rst/states.py/#L2689-L2690

...and that is only relevant when an existing alt attribute is _not_ found from
the node here:

  https://sources.debian.org/src/python-docutils/0.20.1%2Bdfsg-3/docutils/writers/_html_base.py/#L1084


The reason I'd like to know this is to determine the feasibility of a fix that
would apply across multiple buildsites (not only python-pyswarms-doc).

A naive fix idea would be to modify nbsphinx to emit an empty-string alt option
in cases where no existing alt attribute was found on the HTML <img> element.

However: I'm not yet sure about the implicit contracts/conventions are between
these components (nbsphinx, docutils), so I may need to investigate/discuss
further.