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

On 30/10/20 18:46, Peter Maydell wrote:
> 
> 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.

FWIW I've sent to Linux our other two local patches, and if you are okay
with it I can also do the sync in the other direction before 5.2 (the
plan was to do it afterwards).

Paolo

On Fri, 30 Oct 2020 at 18:20, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 30/10/20 18:46, Peter Maydell wrote:
> >
> > 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.
>
> FWIW I've sent to Linux our other two local patches, and if you are okay
> with it I can also do the sync in the other direction before 5.2 (the
> plan was to do it afterwards).

Probably safer to sync afterwards. Do you have a link to the
patches you've sent in the Linux direction ?

thanks
-- PMM

On Fri, 30 Oct 2020 at 19:12, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Fri, 30 Oct 2020 at 18:20, Paolo Bonzini <pbonzini@redhat.com> wrote:
> >
> > On 30/10/20 18:46, Peter Maydell wrote:
> > >
> > > 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.
> >
> > FWIW I've sent to Linux our other two local patches, and if you are okay
> > with it I can also do the sync in the other direction before 5.2 (the
> > plan was to do it afterwards).
>
> Probably safer to sync afterwards. Do you have a link to the
> patches you've sent in the Linux direction ?

Having actually looked at the current state of the kernel's
kernel-doc script I see somebody has already done the
necessary updates for Sphinx 3 compatibility. So we have
two choices for 5.2:
 * take this patch 1 as a minimal fix
 * do the sync of the kernel's version of the script

I'll have a look at how painful or otherwise the sync is, I guess.
We only use the kerneldoc stuff in the 'devel' manual which
is not really userfacing anyway.

thanks
-- PMM

On 30/10/20 21:02, Peter Maydell wrote:
> Having actually looked at the current state of the kernel's
> kernel-doc script I see somebody has already done the
> necessary updates for Sphinx 3 compatibility. So we have
> two choices for 5.2:
>  * take this patch 1 as a minimal fix
>  * do the sync of the kernel's version of the script
> 
> I'll have a look at how painful or otherwise the sync is, I guess.
> We only use the kerneldoc stuff in the 'devel' manual which
> is not really userfacing anyway.

Oh nice! I had a slightly older Linux checkout and it wasn't there yet.
 I think you can go ahead with these two patches, I'll take care of the
sync for 6.0.

Here are our two patches.

https://lore.kernel.org/linux-doc/20201030144713.201372-1-pbonzini@redhat.com/T/#t