[Debian-astro-maintainers] Bug#1064858: python-astroplan-doc: please make the package build reproducible.

[James Addison]

Package: python-astroplan-doc
Severity: wishlist
User: reproducible-builds at lists.alioth.debian.org
Usertags: timestamps randomness

Dear Maintainer,

I'm an occasional volunteer contributor to the Reproducible Builds[1] project,
and noticed recently that the python-astroplan-doc package failed[2] an
automated Debian package reproducibility test.

There appear to be two causes of non-reproducibility:

  * Unless instructed otherwise, the Sphinx autodoc extension evaluates the
    default values of Python method signature arguments.  In the case of
    astroplan, that produces timing information that is relative to the
    build-time of the project (such as the value of '_current_year_time_range'
    in the arguments to 'months_observable'[3]).

  * The astroplan docs include build-time-generated matplotlib diagrams in SVG
    format.  By default, matplotlib uses[4] a randomly-generated UUID4 scheme
    to add a salt when creating the path IDs in those SVG files, meaning that
    the resulting documentation varies on each build.

I can suggest two corresponding resolutions to make the documentation build
reproducibly:

  * We can use the 'autodoc_preserve_defaults' configuration option[5] in the
    autodoc extension to include the source code text of each argument default,
    instead of the build-time values they evaluate to.

  * We can configure the matplotlib 'svg.hashsalt' option[6].  This can be
    configured on a per-diagram basis, or globally using a matplotlibrc file.
    In this case, I recommend the latter because this should mean that we do
    not have to modify the source package, only the Debian packaging.

I'll provide a merge request on Salsa with these suggestions and will link that
to the bugreport here.

Regards,
James

[1] - https://reproducible-builds.org

[2] - https://tests.reproducible-builds.org/debian/rb-pkg/unstable/arm64/diffoscope-results/astroplan.html

[3] - https://salsa.debian.org/debian-astro-team/astroplan/-/blob/ffea5b68f3f4e682b0226a11b24df9c7ef56ff2c/astroplan/constraints.py#L1094-1096

[4] - https://sources.debian.org/src/matplotlib/3.6.3-1/lib/matplotlib/backends/backend_svg.py/#L497-L498

[5] - https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_preserve_defaults

[6] - https://matplotlib.org/stable/users/explain/customizing.html?highlight=svg.hashsalt#matplotlibrc-sample