Bug 14835

Summary:	Need autobuilder to build docs with at least Sphinx 4.0
Product:	[Infrastructure] AutoBuilder	Reporter:	Michael Opdenacker <michael.opdenacker>
Component:	autobuilder	Assignee:	Antonin Godard <antonin.godard>
Status:	RESOLVED FIXED	QA Contact:
Severity:	normal
Priority:	Medium+	CC:	foss+yocto, infras.ab.watcher, Infras.watcher, michael.opdenacker, pidge, randy.macleod, richard.purdie
Version:	unspecified
Target Milestone:	5.2 M4
Hardware:	x86
OS:	Multiple
Whiteboard:
OS type for building Yocto:	---	Type of Regression:	---
Verified:		Documentation change:	Yes (doc changes required)

Description Michael Opdenacker 2022-06-10 16:03:13 UTC

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).

Comment 1 Michael Opdenacker 2022-06-16 14:36:50 UTC

Richard to setup the autobuilder to run tests and figure out which packages we need to achieve this.

Comment 2 Richard Purdie 2022-06-16 15:44:05 UTC

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

Comment 3 Richard Purdie 2022-06-16 16:04:56 UTC

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?

Comment 4 Michael Opdenacker 2022-06-16 16:30:15 UTC

Great! Thanks for the progress.
I sent a new pull-request for master.
Thanks again
Michael.

Comment 5 Richard Purdie 2022-08-10 20:22:08 UTC

Was this completed?

Comment 6 Quentin Schulz 2022-08-12 14:37:21 UTC

(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

Comment 7 Randy MacLeod 2024-10-24 15:04:01 UTC

Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB.

Comment 8 Antonin Godard 2025-02-18 10:08:30 UTC

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

Comment 9 Richard Purdie 2025-02-20 22:19:33 UTC

I believe this has been addressed and the issue resolved. Thanks!