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

[Peter Maydell]

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