Our current docs don't build with Sphinx 3, as noted in https://bugs.launchpad.net/bugs/1872113 -- this is a combination of: (1) we are using the sphinx-build -W option so warnings are treated as errors (3) a kernel-doc script bug meant it was omitting a close-paren when a function parameter was a function pointer; older Sphinx ignored this but Sphinx 3 parses the function declaration and warns about it; and because of (1) this is fatal to the QEMU build (2) Sphinx 3 makes a breaking change in how it wants C structs to be marked up (moving from 'c:type:: struct Foo' to 'c:struct:: Foo'); our use of the old syntax provokes a warning, which again because of point (1) is fatal
Patch 1 extends configure's --disable-werror to cover Sphinx as well as the C compiler, so that at least there is a workaround (which will be automatic for release builds). Patch 2 fixes the trivial kernel-doc bug. Patch 3 adds and uses a new --sphinx-version option to kernel-doc, so that our Sphinx plugin can pass the Sphinx version down and the script can then choose the right syntax. I've marked this up as 'for-5.0?' because I think it would be nice if at least patch 1 went in. Patch 2 seems uncontroversial (though I guess we should forward it up to the kernel folks since kernel-doc is from them originally). Patch 3 is the expedient change, but you could argue about whether this is the best way to tell kernel-doc what to do. thanks -- PMM Peter Maydell (3): configure: Honour --disable-werror for Sphinx scripts/kernel-doc: Add missing close-paren in c:function directives kernel-doc: Use c:struct for Sphinx 3.0 and later configure | 9 ++++++++- Makefile | 2 +- docs/sphinx/kerneldoc.py | 1 + scripts/kernel-doc | 18 ++++++++++++++++-- 4 files changed, 26 insertions(+), 4 deletions(-) -- 2.20.1