Emergent error in docs builds

[jaraco]

Last week, docs builds were fine, but attempting to make the 71.0.0 release today, docs builds are failing:

 setuptools main [1] 🐚 git push -f
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 12 threads
Compressing objects: 100% (8/8), done.
Writing objects: 100% (8/8), 1.30 KiB | 1.30 MiB/s, done.
Total 8 (delta 7), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (7/7), completed with 7 local objects.
To https://github.com/pypa/setuptools
 + f2cd90fde...6c6e2e168 main -> main (forced update)
 setuptools main 🐚 tox -e docs
docs: install_deps> python -I -m pip install 'importlib_resources<6'
.pkg: _optional_hooks> python '/Users/jaraco/Library/Application Support/pipx/venvs/tox/lib/python3.12/site-packages/pyproject_api/_backend.py' True setuptools.build_meta
.pkg: get_requires_for_build_editable> python '/Users/jaraco/Library/Application Support/pipx/venvs/tox/lib/python3.12/site-packages/pyproject_api/_backend.py' True setuptools.build_meta
.pkg: build_editable> python '/Users/jaraco/Library/Application Support/pipx/venvs/tox/lib/python3.12/site-packages/pyproject_api/_backend.py' True setuptools.build_meta
docs: install_package_deps> python -I -m pip install 'build[virtualenv]>=1.0.3' 'filelock>=3.4.0' furo importlib_metadata 'ini2toml[lite]>=0.14' 'jaraco.develop>=7.21; python_version >= "3.9" and sys_platform != "cygwin"' 'jaraco.envs>=2.2' 'jaraco.packaging>=9.3' 'jaraco.path>=3.2.0' jaraco.test 'jaraco.tidelift>=1.4' mypy==1.10.0 'packaging>=23.2' 'pip>=19.1' pygments-github-lexers==0.0.5 'pyproject-hooks!=1.1' 'pytest!=8.1.*,>=6' 'pytest-checkdocs>=2.4' pytest-cov 'pytest-enabler>=2.2' 'pytest-home>=0.5' pytest-mypy 'pytest-perf; sys_platform != "cygwin"' 'pytest-ruff<0.4; platform_system == "Windows"' 'pytest-ruff>=0.2.1; sys_platform != "cygwin"' 'pytest-ruff>=0.3.2; sys_platform != "cygwin"' pytest-subprocess pytest-timeout 'pytest-xdist>=3' 'rst.linker>=1.9' sphinx-favicon sphinx-inline-tabs sphinx-lint 'sphinx-notfound-page<2,>=1' sphinx-reredirects 'sphinx>=3.5' sphinxcontrib-towncrier tomli 'tomli-w>=1.0.0' 'virtualenv>=13.0.0' wheel
docs: install_package> python -I -m pip install --force-reinstall --no-deps /Users/jaraco/code/pypa/setuptools/.tox/.tmp/package/83/setuptools-71.0.0.post20240717-0.editable-py3-none-any.whl
docs: commands[0] /Users/jaraco/code/pypa/setuptools/docs> python -m sphinx -W --keep-going . /Users/jaraco/code/pypa/setuptools/build/html
Running Sphinx v7.4.5
loading translations [en]... done
making output directory... done
loading intersphinx inventory 'python' from https://docs.python.org/3.11/objects.inv...
loading intersphinx inventory 'pip' from https://pip.pypa.io/en/latest/objects.inv...
loading intersphinx inventory 'build' from https://pypa-build.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory 'PyPUG' from https://packaging.python.org/en/latest/objects.inv...
loading intersphinx inventory 'packaging' from https://packaging.pypa.io/en/latest/objects.inv...
loading intersphinx inventory 'twine' from https://twine.readthedocs.io/en/stable/objects.inv...
loading intersphinx inventory 'importlib-resources' from https://importlib-resources.readthedocs.io/en/latest/objects.inv...
intersphinx inventory has moved: https://pypa-build.readthedocs.io/en/latest/objects.inv -> https://build.pypa.io/en/latest/objects.inv
WARNING: inventory <https://build.pypa.io/en/latest> contains multiple definitions for std:label:python--m-build--v
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 48 source files that are out of date
updating environment: [new config] 48 added, 0 changed, 0 removed
/Users/jaraco/code/pypa/setuptools/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/ext.py:66: EncodingWarning: 'encoding' argument not specified.
  towncrier_output = subprocess.check_output(  # noqa: S603
reading sources... [100%] userguide/quickstart
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... done
copying extra files... done
copying assets: done
writing output... [100%] userguide/quickstart
generating indices... genindex py-modindex done
Creating redirect 'userguide/keywords.html' to '/deprecated/changed_keywords.html'.
Creating redirect 'userguide/commands.html' to '/deprecated/commands.html'.
writing additional pages... search done
copying images... [100%] images/banner-640x320.svg
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.
docs: exit 1 (13.54 seconds) /Users/jaraco/code/pypa/setuptools/docs> python -m sphinx -W --keep-going . /Users/jaraco/code/pypa/setuptools/build/html pid=72058
  docs: FAIL code 1 (35.32=setup[21.78]+cmd[13.54] seconds)
  evaluation failed :( (35.36 seconds)

I believe the warning treated as error in sphinxcontrib/towncrier was previously reported in sphinx-contrib/sphinxcontrib-towncrier#91, but somehow it's now blocking builds.

[jaraco]

I checked the release history for the project, but nothing was released recently. Maybe that warning isn't the emergent cause. Mabye it's the "multiple definitions for std:label:python--m-build--v".

[jaraco]

Confirmed - the issue isn't related to sphinxcontrib-towncrier, but instead to the "multiple definitions" in the build docs. Also, the warning only appears on the first build. On a second build, they complete successfully (apparently relying on a cache of intersphinx labels).

[webknjaz]

Yeah, I was about to point that out.. One warning is coming from the interpreter and the other from the Sphinx realm.

[jaraco]

Turns out that simply updating the redirecting docs works around the warning/error about multiple definitions, but it reveals a new issue in the updated docs:

/Users/jaraco/code/pypa/setuptools/docs/userguide/quickstart.rst:22: WARNING: unknown document: 'build:installation'

[jaraco]

There doesn't appear to be anything meaningful about installation in the build docs, so that must have just gotten removed.

No, that's not it. When I look at the sources in github, there's definitely an installation section.

It seems that maybe the build project in readthedocs only has 1.0.2 as the latest build, even though the code is now much newer.

But what's even stranger is there is no 1.0.2 tag in the build project. So who knows where that docs build came from.

[jaraco]

Interestingly, there is a 1.0.3 and 1.0.1, and both of those have a docs/installation.rst, which makes me think the build.readthedocs.io is not the right project. Indeed, looking at the docs, I see that it's for an unrelated project.

So why is pypa-build redirecting to build?

[webknjaz]

So why is pypa-build redirecting to build?

It's redirecting from pypa-build.rtfd.io to build.pypa.io. It's a different FQDN.

[webknjaz]

But what's even stranger is there is no 1.0.2 tag in the build project. So who knows where that docs build came from.

It's not. It's something else, created in 2015.

[webknjaz]

and both of those have a docs/installation.rst

I recommend using intersphinx to inspect what the website exposes right now. I've built a thing for myself that presents that as an html table (and updates every 4 hours): https://webknjaz.github.io/intersphinx-untangled/pypa-build.rtfd.io/. Feel free to use it to figure out the reference you need.

[webknjaz]

WARNING: inventory https://build.pypa.io/en/latest contains multiple definitions for std:label:python--m-build--v

There's https://build.pypa.io/en/latest/index.html#python--m-build--V and https://build.pypa.io/en/latest/index.html#python--m-build--v. I wonder if Sphinx makes some sort of case-insensitive comparison and errors out because of that.

You could try older Sphinx to see if it's a regression.

[webknjaz]

Ah.. I see that Sphinx 7.4.4 is supposed to contain a fix for this.

[jayaddison]

Ah.. I see that Sphinx 7.4.4 is supposed to contain a fix for this.

This refers to sphinx-doc/sphinx#12586 I think - and yep, it does relate to the same warning message.

However: I do not think that it will silence the warning in this particular situation; the v and V entries refer to different entities, but if an external project references either of those, then the resolved hyperlink for that project will point to the first one that appears in object.inv -- Intersphinx matching in these cases is case-insensitive, and that's what the message is trying to flag.

sphinx-doc/sphinx#12586 reduced the log severity in the case of duplicates (both v and V pointing to the same entity -- so the hyperlink would be correct regardless of definition order in objects.inv order) -- but I felt that we should continue to warn about genuinely ambiguous entries.

This case makes me think that perhaps we should also reduce the log-severity even when there is ambiguity found when loading objects.inv files.

[jayaddison]

PS: For an interim workaround if you do want to upgrade, you can suppress these warnings following some guidance from here (quoting @AA-Turner):

Thank you for opening this ... (). This was introduced in 799ae16 (#12329). You can suppress it with 'intersphinx.external' in your suppress_warnings, though the warning is alerting you to that intersphinx has encountered an ambiguity in resolution.