Skip to content

Documentation build fails with Sphinx 8

Reported upstream in Gentoo at https://bugs.gentoo.org/936620

Reported to sphinx at https://github.com/sphinx-doc/sphinx/issues/12686

The issue here is that sphinx has at least in some places been providing deprecation warnings that functions which return paths are gonna stop allowing you to use them as str, and start returning pathlib.Path. It doesn't appear that the API used in the depfile writer plugin actually had such a warning, but nonetheless... it now returns a Path.

The resulting build error looks like this:

[45/908] /usr/bin/env CONFDIR=/etc/qemu /usr/bin/sphinx-build -q -j auto -Dversion=9.0.2 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_stamp=docs/docs.stamp -b html -d /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/tools-build/docs/manual.p /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/docs /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/tools-build/docs/manual
FAILED: docs/docs.stamp 
/usr/bin/env CONFDIR=/etc/qemu /usr/bin/sphinx-build -q -j auto -Dversion=9.0.2 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_stamp=docs/docs.stamp -b html -d /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/tools-build/docs/manual.p /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/docs /var/tmp/portage/app-emulation/qemu-9.0.2/work/qemu-9.0.2/tools-build/docs/manual

Extension error (depfile):
Handler <function write_depfile at 0x77a1775ff560> for event 'build-finished' threw an exception (exception: unsupported operand type(s) for +: 'PosixPath' and 'str')
ninja: build stopped: subcommand failed.

The relevant code is https://gitlab.com/qemu-project/qemu/-/blob/029e13a8a56a2931e7c24c0db52ae7256b932cb0/docs/sphinx/depfile.py#L20-54

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information