[Docs] RTD changelog is out of date

[jwodder]

Summary

The changelog on the RTD site is missing entries for the last four releases (v54.1.1, v54.1.2, v54.1.3, v54.2.0).

OS / Environment

No response

Code of Conduct

• I agree to follow the PSF Code of Conduct

[webknjaz]

There's a bunch of failed builds on RTD: https://readthedocs.org/projects/setuptools/builds/. So it's not just the changelog but the whole docs site.

[webknjaz]

The first failed log from is from 3 weeks ago:

Running Sphinx v1.8.5
loading translations [en]... done

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/registry.py", line 472, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx_inline_tabs/__init__.py", line 5, in <module>
    from ._impl import setup  # noqa
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx_inline_tabs/_impl.py", line 8, in <module>
    from sphinx.transforms.post_transforms import SphinxPostTransform
ImportError: cannot import name 'SphinxPostTransform' from 'sphinx.transforms.post_transforms' (/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/transforms/post_transforms/__init__.py)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 303, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 228, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 449, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/registry.py", line 475, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname, err)
sphinx.errors.ExtensionError: Could not import extension sphinx_inline_tabs (exception: cannot import name 'SphinxPostTransform' from 'sphinx.transforms.post_transforms' (/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/transforms/post_transforms/__init__.py))

Extension error:
Could not import extension sphinx_inline_tabs (exception: cannot import name 'SphinxPostTransform' from 'sphinx.transforms.post_transforms' (/home/docs/checkouts/readthedocs.org/user_builds/setuptools/envs/latest/lib/python3.7/site-packages/sphinx/transforms/post_transforms/__init__.py))

(https://readthedocs.org/projects/setuptools/builds/13171300/)

[webknjaz]

Looks like sphinx_inline_tabs tries to import things from the modern Sphinx versions that aren't present in v1.8.5. The solution could be setting the version in the requirements files of this repo.

cc @pradyunsg does the extension set any minimum version of Sphinx?

[webknjaz]

The PR that broke RTD is #2584.
@jaraco with #2469 this could've been prevented (because Netlify is clearly configured differently than RTD) — the status of the broken docs site would've appeared in the PR statuses.

[webknjaz]

Upstream bug: pradyunsg/sphinx-inline-tabs#14

[jaraco]

with #2469 this could've been prevented

Agreed. Also, if there were another publishing method that did not depend on RTD (Github-hosted docs), that might also have avoided the issue. I'm unsure how much energy I want to expend on RTD. I'd really like to have a near-zero workflow for docs publishing. Maybe RTD support in pull requests would be nice, but not if enabling that has a high enough barrier that it requires substantial manual intervention on every project.

Sorry if that sounded ranty; I just want to be careful about biting off more maintenance burden.

[webknjaz]

Sure. IIRC they've implemented API changes to support toggling this automatically: readthedocs/readthedocs.org#7834. I documented this earlier @ jaraco/skeleton#41.

[jaraco]

For now the workaround addresses this issue.

[pradyunsg]

The latest release of sphinx-inline-tabs should fix this issue. :)

[webknjaz]

Final fix: #2622