fix: ensure reproducible documentation builds wrt SOURCE_DATE_EPOCH (#2568)

* fix: ensure reproducible documentation builds wrt `SOURCE_DATE_EPOCH`

* docs: add a newsfragment

Author: vytas7

docs/_newsfragments/2567.bugfix.rst

@@ -0,0 +1,5 @@
+Falcon's documentation build process was not fully reproducible, as the output
+could vary with the build system's date. The issue was addressed by adding
+support for setting the build date via the
+`SOURCE_DATE_EPOCH <https://reproducible-builds.org/docs/source-date-epoch/>`__
+standardized environment variable.

docs/conf.py

@@ -21,6 +21,7 @@
 import multiprocessing
 import os
 import sys
+import time
 
 try:
     import falconry_pygments_theme
@@ -65,9 +66,15 @@
     for component in _version_components
 )
 
+# NOTE(vytas): Afford overriding the current date with SOURCE_DATE_EPOCH for
+#   reproducible documentation builds.
+#   (See also: https://reproducible-builds.org/docs/source-date-epoch/)
+build_date = datetime.datetime.fromtimestamp(
+    int(os.environ.get('SOURCE_DATE_EPOCH', time.time())), tz=datetime.timezone.utc
+)
 
 project = 'Falcon'
-copyright = f'{datetime.datetime.now().year} Falcon Contributors'
+copyright = f'{build_date.year} Falcon Contributors'
 author = 'Kurt Griffiths et al.'
 version = '.'.join(_version_components[0:2])
 release = falcon.__version__

docs/ext/falcon_releases.py

@@ -23,8 +23,10 @@
 import datetime
 import enum
 import itertools
+import os
 import pathlib
 import re
+import time
 
 import sphinx.util.docutils
 
@@ -136,6 +138,17 @@ class FalconReleasesDirective(sphinx.util.docutils.SphinxDirective):
     required_arguments = 1
     has_content = True
 
+    @staticmethod
+    def get_build_date():
+        # NOTE(vytas,bmwiedemann): Afford overriding the current date with
+        #   SOURCE_DATE_EPOCH for reproducible documentation builds.
+        #   (See also: https://reproducible-builds.org/docs/source-date-epoch/)
+        build_date = datetime.datetime.fromtimestamp(
+            int(os.environ.get('SOURCE_DATE_EPOCH', time.time())),
+            tz=datetime.timezone.utc,
+        )
+        return build_date.date()
+
     def run(self):
         changelog_path = pathlib.Path(self.arguments[0])
         if not changelog_path.is_absolute():
@@ -184,7 +197,7 @@ def run(self):
                 eol_date = (
                     current_series[0].first.date + self._OLDSTABLE_MAINTENANCE_PERIOD
                 )
-                if datetime.date.today() < eol_date:
+                if self.get_build_date() < eol_date:
                     status = _ReleaseStatus.security
                     # NOTE(vytas): Move to a new line because otherwise table
                     #   layout gets messed up in an unpleasant way.

tox.ini

@@ -337,11 +337,17 @@ commands =
 # --------------------------------------------------------------------
 
 [testenv:docs]
+# NOTE(vytas): For easy testing of reproducible documentation builds.
+#   (See also: https://reproducible-builds.org/docs/source-date-epoch/)
+passenv = SOURCE_DATE_EPOCH
 deps = -r{toxinidir}/requirements/docs
 commands =
     sphinx-build -j auto -W -E -b html docs docs/_build/html []
 
 [testenv:towncrier]
+# NOTE(vytas): For easy testing of reproducible documentation builds.
+#   (See also: https://reproducible-builds.org/docs/source-date-epoch/)
+passenv = SOURCE_DATE_EPOCH
 deps = -r{toxinidir}/requirements/docs
         toml
         towncrier