Skip to content

docs: Fix building with Sphinx 3.2

Peter Maydell qemu-devel 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest2 patches 8 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/2scripts/kerneldoc: For Sphinx 3 use c:macro for macros with argumentsscripts/kernel-doc+17 -12 replies
2/2qemu-option-trace.rst.inc: Don't use option:: markupdocs/qemu-option-trace.rst.inc+3 -32 replies

Reviews trailers per patch

All 2 patches have a Reviewed-by or Acked-by.

PatchDaniel P. BerrangéStefan Hajnoczi
1/2R-b T-b
2/2R-b T-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v1 thread

Cover letter [PATCH 0/2] docs: Fix building with Sphinx 3.2

This patchseries fixes some issues with building our docs with Sphinx 3.2:
* kerneldoc was using the 'c:function' directive for both functions and macros, but Sphinx 3.2 wants 'c:macro' for macros and complains if the argument to 'c:function' isn't parseable as a function declaration
* qemu-option-trace.rst.inc's use of option:: provokes a warning in Sphinx 3.2

We fix the first by making kerneldoc output the right directive depending on the Sphinx version it's working with, and fix the second by just dropping our usage of option:: in favour of a simple definition-list markup.

This does mean our kernel-doc gets another patch that makes it diverge a little from the kernel's version, but we already have one of those (commit 152d1967f650f67b7e). I do want to try to upstream these to the kernel, but that will require more work I suspect since the kernel makes much more extensive use of kernel-doc and probably also has other issues when building with newer Sphinxes. For the moment I would like us to release QEMU 5.2 with docs that build with all the Sphinxes we know about.

Tested by building with Sphinx 1.6.1, 2.0, 2.4, 3.0 and 3.2.

thanks
-- PMM

Peter Maydell (2):
scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments qemu-option-trace.rst.inc: Don't use option:: markup

 docs/qemu-option-trace.rst.inc |  6 +++---
 scripts/kernel-doc             | 18 +++++++++++++++++-
 2 files changed, 20 insertions(+), 4 deletions(-)
Signature · 1 line
2.20.1