Sphinx: localisation changes / reproducibility

[James Addison]

Hi folks,

A set of reproducible-build-related changes[1] that I've developed for
sphinx (a documentation project generator) have been accepted for
inclusion in v6.2.0 of sphinx.

I'm optimistic that those changes can address a sizable category[2] of
reproducible build failures related to translation of documentation
during software builds (reproducible build testing intentionally
varies the host LANGUAGE setting to shake out unintended sources of
build variation, and some sphinx projects fail rb-tests due to that).

However.. with the changes merged (although not yet released) I'm
beginning to have some doubts about them.

The positive effect of the changes is that I expect they'll help to
confirm and achieve reproducibility for a good chunk of remaining
non-reproducible software.

The downside is: disabling localization -- or perhaps more accurately:
emitting all documentation for each project using 'null'[3]
translation -- seems like a fairly blunt, and perhaps unwelcome (for
consumers) way to achieve reproducibility.


A longer, better path to achieve reproducibility would be to support
building documentation in _all_ available translated locales during
Sphinx project builds (something that is not yet supported -- and with
at least one component that I'm aware of (objects.inv) that doesn't
seem to support multi-language content).  Doing that should produce
output artifacts that users of any supported locale can access in a
relevant localised way, and that can be made bit-for-bit consistent.

In summary: I'm writing partly optimistically because I think the
merged changes could improve and help to confirm reproducibility of
software during testing.  But I also feel a bit conflicted about the
way I've approached the changes and their implications, so I'm also
keen to gather feedback and thoughts.

Thank you,
James

[1] - https://github.com/sphinx-doc/sphinx/pull/10949

[2] - https://tests.reproducible-builds.org/debian/issues/unstable/sphinxdoc_translations_issue.html

[3] - https://docs.python.org/3/library/gettext.html#the-nulltranslations-class