qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Peter Maydell
Subject: [PATCH 0/2] docs: Fix building with Sphinx 3.2
Date: Fri, 30 Oct 2020 17:46:58 +0000

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

-- 
2.20.1




reply via email to

[Prev in Thread] Current Thread [Next in Thread]