Sphinx: copyright substitution and reproducibility

[James Addison]

Hi again,

On Tue, 9 Jul 2024 at 12:14, James Addison <jay at jp-hosting.net> wrote:
> [ ... snip ... ]
> The very-abbreviated problem statement is that when SOURCE_DATE_EPOCH is
> configured, Sphinx projects that have configured their copyright notices using
> dynamic elements can produce nonsensical output under some circumstances.

The recently-released Sphinx v8.1.x series includes improvements to reduce the
number of invalid copyright notice substitution edge-cases.

In particular:

  * Logic is modified[1] to restrict the substitutions:
    * Only copyright lines that mention the current system clock year are
      eligible for substitution.
    * Substitution only occurs when the replacement year (sourced from
      SOURCE_DATE_EPOCH) is less than the current year.

  * A placeholder value of '%Y' becomes available[2] as a method to dynamically
    add a year value to copyright lines; this allows migration away from the
    approach some projects were using of writing Python code in their
    configuration files to achieve the same effect.

With credit to Adam Turner from the Sphinx project for adapting the initial
changesets I'd suggested.

Regards,
James

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

[2] - https://github.com/sphinx-doc/sphinx/pull/12910