RTD build failing

[lmoureaux]

Describe the bug

RTD failed in #2022 with:

Manuals/Program/freeciv21-server.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.

I think it doesn't like the double space after the dots:

..  SPDX-License-Identifier: GPL-3.0-or-later
..  SPDX-FileCopyrightText: James Robertson <[email protected]>

To Reproduce
Steps to reproduce the behavior:

1. Trigger an RTD build
2. Watch it fail

[lmoureaux]

Temporarily disabled the requirement that RTD passes to merge PRs

[jwrober]

Something has changed at RTD then. Since that has been in there for some time and was not failing before.

[daavko]

Seems like it got broken by RTD updating Sphinx to 7.2.2 - last successful build seems to be with Sphinx 6.2.1 by looking at the raw logs. A quick workaround might be to pin Sphinx to v6 if that's possible.

Poking around a bit more, it seems like it fails due to the sphinx-last-updated-by-git plugin throwing an assertion error for some reason. Looking at the code, the only time that assertion is ran is for a source-read event from Sphinx which seems to have been touched recently in sphinx-doc/sphinx#11510) which fixed sphinx-doc/sphinx#10678. I'd assume the plugin simply doesn't expect the new behavior for the event, and the fact that it may now return None for one of the parameters in some cases. That would make it a similar bug to this one: sphinx-gallery/sphinx-gallery#1175, possibly with some extra steps.

That's about as far as my momentary interest got me with this. An issue for the plugin author would probably be in order. Or use a different plugin for the "last updated" thing in the footer.

Wrt the warning about explicit markup not ending with a blank line, that isn't a new thing. It occurs even in successful builds. Just take a look at the raw logs. There's plenty more warnings other than for the explicit markup.

[lmoureaux]

Upstream bugs have been fixed. We can use sphinx_last_updated_by_git >= 0.3.6 with sphinx > 7.2.5 once the latter has been released.