With the latest versions of Sphinx (5.0.1 at the time of this writing), building the docs fails because of this warning (warnings are treated as errors): WARNING: extlinks: Sphinx-6.0 will require a caption string to contain exactly one '%s' and all other '%' need to be escaped as '%%'. To solve this, a solution would be to revert this commit: https://git.yoctoproject.org/yocto-docs/commit/?id=c9922076f5c1285d9cfd6aff8ce5b6635d88222f However, this would be incompatible with the current version of Sphinx used on the autobuilder to build the docs. Here are details from Quentin Schulz: If we revert the patch, we need to use a newer Sphinx for building the docs with the autobuilder (currently 3.2.1) otherwise we get CVE-%s-<CVE_ID> instead of CVE-<CVE_ID>. We'd need a patch that bumps the minimum version of Sphinx to build the docs (in conf.py, needs_sphinx), revert the patch and use a new docs_buildtools in the autobuilder. Without this you're just fixing your a build issue on your local PC and failing the autobuilder. We do not have a "stable" release available yet on https://autobuilder.yocto.io/pub/buildtools/ so we'd need to create one. I know Richard made an attempt a few months ago when we added Sphinx recipe inside poky (specifically for creating the docs buildtools).
Richard to setup the autobuilder to run tests and figure out which packages we need to achieve this.
What needs to happen here is to make a buildtools build with "deploy artefacts" checked. I did this, the result was here: http://autobuilder.yocto.io/pub/non-release/20220616-20/buildtools/ we then add a patch to autobuilder helper to patch the new tarball into run-docs-build, I added one to the master-next branch there. We then trigger a docs build using that branch of autobuilder-helper. I did this here, not sure what broke though: https://autobuilder.yoctoproject.org/typhoon/#/builders/114/builds/478/steps/5/logs/stdio
I fixed that issue, now we see other issues that Michael mentioned: https://autobuilder.yoctoproject.org/typhoon/#/builders/114/builds/480/steps/5/logs/stdio Could you push fixes for those onto the yocto-docs master-next branch and then we can merge everything once builds pass?
Great! Thanks for the progress. I sent a new pull-request for master. Thanks again Michael.
Was this completed?
(In reply to comment #5) > Was this completed? Technically, yes. But this resulted in other bugs, c.f. https://lists.yoctoproject.org/g/yocto/message/57450
Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB.
Hi, We are now using Sphinx on version 8.0.2 to build the master, styhead, and scarthgap branches of the documentation. Out of the maintained branches, only kirkstone is built using Sphinx 5.1.1, but even then, it is newer than the old version mentioned here (3.2.1). Older branches/tags are also built with Sphinx 5.1.1. So if my understanding is correct, this bug can be closed? I don't think there's any of the issues there remaining? Can someone confirm? Antonin
I believe this has been addressed and the issue resolved. Thanks!