Hosted documentation has not been updated in over a week

[aphedges]

Documentation

I tried viewing the Changelog to see what was included in the Python 3.12.5 release, and I noticed the page states "Last updated on Jul 31, 2024 (11:04 UTC)". I checked several other pages on the 3.12 documentation site, and they all have the same date. I checked the 3.13 and 3.14 docs, and both of them were built earlier today. The older documentation should be rebuilt whenever there is a release so the changelog can be read.

Linked PRs

• gh-122868: Add lower bounds for sphinxcontrib dependencies #122870
• [3.13] gh-122868: Add lower bounds for sphinxcontrib dependencies (GH-122870) #122871
• [3.12] gh-122868: Add lower bounds for sphinxcontrib dependencies (GH-122870) #122872
• gh-122868: Add more lower bounds for sphinxcontrib dependencies #122891
• [3.13] gh-122868: Add more lower bounds for sphinxcontrib dependencies (GH-122891) #122893
• [3.12] gh-122868: Add more lower bounds for sphinxcontrib dependencies (GH-122891) #122894

[hugovk]

Thanks for the report. They should be built roughly every 24 hours.

I see the 3.13 docs were updated an hour ago, and 3.14 docs some 14 hours ago, so looks like this is just affecting 3.12.

@JulienPalard Please could you check the 3.12 docs build on the server?

[hugovk]

I also have access to the docs server, and this is in /var/log/docsbuild/docsbuild.log:

2024-08-09 12:08:45,929 INFO en/3.12: Running.
2024-08-09 12:08:45,929 DEBUG en/3.12: Run: 'git -C /srv/docsbuild/cpython show-ref -s origin/3.12'
2024-08-09 12:08:45,932 DEBUG en/3.12: Run: 'git -C /srv/docsbuild/cpython reset --hard c536f59c62eca95f0f4ef3fd688f5c387dd40ae6 --'
2024-08-09 12:08:45,956 DEBUG en/3.12: https://sentry.io:443 "POST /api/1307574/store/ HTTP/1.1" 200 41
2024-08-09 12:08:45,957 DEBUG en/3.12: Run: 'git -C /srv/docsbuild/cpython clean -dfqx'
2024-08-09 12:08:45,996 DEBUG en/3.12: https://sentry.io:443 "POST /api/1307574/store/ HTTP/1.1" 200 41
2024-08-09 12:08:46,079 DEBUG en/3.12: Run: 'git -C /srv/docsbuild/cpython rev-parse HEAD'
2024-08-09 12:08:46,082 DEBUG en/3.12: Run: 'git -C /srv/docsbuild/cpython diff --name-only efba83f9864eaac63ec0937c2f256f2a8c16191e c536f59c62eca95f0f4ef3fd688f5c387dd40ae6'
2024-08-09 12:08:46,132 INFO en/3.12: Should rebuild: Doc/ has changed (from efba83f9864eaac63ec0937c2f256f2a8c16191e to c536f59c62eca95f0f4ef3fd688f5c387dd40ae6)
2024-08-09 12:08:46,132 DEBUG en/3.12: Run: '/srv/docsbuild/venv/bin/python -m venv /srv/docsbuild/venv-3.12'
2024-08-09 12:08:48,531 DEBUG en/3.12: Run: '/srv/docsbuild/venv-3.12/bin/python -m pip install --upgrade python-docs-theme jieba -rrequirements.txt'
2024-08-09 12:08:49,715 DEBUG en/3.12: Run: '/srv/docsbuild/venv-3.12/bin/python -m pip freeze --all'
2024-08-09 12:08:50,198 INFO en/3.12: Build start.
2024-08-09 12:08:50,198 INFO en/3.12: Running make autobuild-stable
2024-08-09 12:08:50,198 DEBUG en/3.12: Run: "sed -i 's/ *-A switchers=1//' /srv/docsbuild/cpython/Doc/Makefile"
2024-08-09 12:08:50,204 DEBUG en/3.12: Run: "make -C /srv/docsbuild/cpython/Doc PYTHON=/srv/docsbuild/venv-3.12/bin/python SPHINXBUILD=/srv/docsbuild/venv-3.12/bin/sphinx-build BLURB=/srv/docsbuild/venv-3.12/bin/blurb VENVDIR=/srv/docsbuild/venv-3.12 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q' SPHINXERRORHANDLING= autobuild-stable"
2024-08-09 12:08:54,260 ERROR en/3.12: Run: "make -C /srv/docsbuild/cpython/Doc PYTHON=/srv/docsbuild/venv-3.12/bin/python SPHINXBUILD=/srv/docsbuild/venv-3.12/bin/sphinx-build BLURB=/srv/docsbuild/venv-3.12/bin/blurb VENVDIR=/srv/docsbuild/venv-3.12 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q' SPHINXERRORHANDLING= autobuild-stable" KO:
    mkdir -p dist
    # archive the HTML
    make html
    make[3]: Entering directory '/srv/docsbuild/cpython/Doc'
    mkdir -p build
    Building NEWS from Misc/NEWS.d with blurb
    /srv/docsbuild/venv-3.12/bin/sphinx-build -b html -d build/doctrees -j auto  -D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q -Ea -A daily=1  . build/html

    Extension error:
    Could not import extension sphinxcontrib.applehelp (exception: cannot import name 'SkipProgressMessage' from 'sphinx.util' (/srv/docsbuild/venv-3.12/lib/python3.10/site-packages/sphinx/util/__init__.py))
    matplotlib is not installed, social cards will not be generated
    make[3]: *** [Makefile:56: build] Error 2
    make[3]: Leaving directory '/srv/docsbuild/cpython/Doc'
    make[2]: *** [Makefile:190: dist] Error 2
    make[2]: Leaving directory '/srv/docsbuild/cpython/Doc'
    make[1]: *** [Makefile:274: autobuild-dev] Error 2
    make[1]: Leaving directory '/srv/docsbuild/cpython/Doc'
    make: *** [Makefile:286: autobuild-stable] Error 2
    make: Leaving directory '/srv/docsbuild/cpython/Doc'

2024-08-09 12:08:54,264 ERROR en/3.12: Badly handled exception, human, please help.
Traceback (most recent call last):
  File "/srv/docsbuild/scripts/build_docs.py", line 655, in run
    self.build()
  File "/srv/docsbuild/scripts/build_docs.py", line 762, in build
    run(
  File "/srv/docsbuild/scripts/build_docs.py", line 247, in run
    result.check_returncode()
  File "/usr/lib/python3.10/subprocess.py", line 457, in check_returncode
    raise CalledProcessError(self.returncode, self.args, self.stdout,
subprocess.CalledProcessError: Command '['make', '-C', '/srv/docsbuild/cpython/Doc', 'PYTHON=/srv/docsbuild/venv-3.12/bin/python', 'SPHINXBUILD=/srv/docsbuild/venv-3.12/bin/sphinx-build', 'BLURB=/srv/docsbuild/venv-3.12/bin/blurb', 'VENVDIR=/srv/docsbuild/venv-3.12', 'SPHINXOPTS=-D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc= -q', 'SPHINXERRORHANDLING=', 'autobuild-stable']' returned non-zero exit status 2.

That error again:

Could not import extension sphinxcontrib.applehelp (exception: cannot import name 'SkipProgressMessage' from 'sphinx.util' (/srv/docsbuild/venv-3.12/lib/python3.10/site-packages/sphinx/util/__init__.py))

Sounds like it's related to #122500, merged on 31st July, which is around the time of the last build.

I can build the 3.12 docs locally, but that's with a clean venv and I think the docs server persists existing venvs.

The server has these Sphinx things in the venv:

$ ls /srv/docsbuild/venv-3.12/lib/python3.10/site-packages/ | grep "sphinx.*dist.info"
sphinx-8.0.2.dist-info
sphinx_autobuild-2024.4.16.dist-info
sphinx_lint-0.6.7.dist-info
sphinx_notfound_page-1.0.4.dist-info
sphinxcontrib_applehelp-1.0.2.dist-info
sphinxcontrib_devhelp-1.0.2.dist-info
sphinxcontrib_htmlhelp-2.0.0.dist-info
sphinxcontrib_jsmath-1.0.1.dist-info
sphinxcontrib_qthelp-1.0.3.dist-info
sphinxcontrib_serializinghtml-1.1.9.dist-info
sphinxext_opengraph-0.9.1.dist-info

However, locally, I have v2 of many of those including sphinxcontrib-applehelp:

 + sphinx==8.0.2
 + sphinx-notfound-page==1.0.4
 + sphinxcontrib-applehelp==2.0.0
 + sphinxcontrib-devhelp==2.0.0
 + sphinxcontrib-htmlhelp==2.1.0
 + sphinxcontrib-jsmath==1.0.1
 + sphinxcontrib-qthelp==2.0.0
 + sphinxcontrib-serializinghtml==2.0.0
 + sphinxext-opengraph==0.9.1

@AA-Turner Do you think we need to supply a minimum version for sphinxcontrib.applehelp? Or should Sphinx specify it?

It might make sense to update https://github.com/python/docsbuild-scripts to clear the venv each time as well. This problem didn't show up on our GitHub Actions or Read the Docs builds, because they start with a clean slate each time.

[ned-deily]

We don't build any applehelp books, AFAIK. Can we just not require it?

[AA-Turner]

Do you think we need to supply a minimum version for sphinxcontrib.applehelp? Or should Sphinx specify it?

sphinxcontrib-applehelp 1.0.3 fixes this issue. I'll add lower-bounds in Sphinx, but that will only fix things going forwards. I remember another dependency issue here though, I thought we fixed it by making pip install and update?

We don't build any applehelp books, AFAIK. Can we just not require it?

It's a core sphinx plugin, we can't remove it (sphinx has odd packaging due to history)

A

[zware]

Suggestion: add --upgrade-strategy=eager to https://github.com/python/docsbuild-scripts/blob/213530446b083788da9dbf4ca02284b5dc9c5c5c/build_docs.py#L792