Re: [PULL v8 00/86] Misc QEMU patches for 2020-09-24

[Paolo Bonzini]

On 02/10/20 20:24, Eduardo Habkost wrote:
> On Fri, Oct 02, 2020 at 06:27:35PM +0200, Paolo Bonzini wrote:
>> On 02/10/20 17:58, Michal Prívozník wrote:
>>>>
>>>
>>> cd442a45db60a1a72fcf980c24bd1227f13f8a87 is the first bad commit
>>>
>>> Sorry for noticing this earlier, but is this known? The build starts
>>> failing for me after this commit:
>>>
>>> /usr/bin/sphinx-build -Dversion=5.1.50 -Drelease= -W
>>> -Ddepfile=docs/devel.d -Ddepfile_stamp=docs/devel.stamp -b html -d
>>> /home/zippy/work/qemu/qemu.git/build/docs/devel.p
>>> /home/zippy/work/qemu/qemu.git/docs/devel
>>> /home/zippy/work/qemu/qemu.git/build/docs/devel
>>> Running Sphinx v3.2.1
>>> building [mo]: targets for 0 po files that are out of date
>>> building [html]: targets for 20 source files that are out of date
>>> updating environment: [new config] 20 added, 0 changed, 0 removed
>>> reading sources... [100%] testing
>>
>> No, this is new.  It works with older versions of Sphinx (I have 2.2.2
>> despite being on Fedora 32 which is pretty recent).
>>
>> For now Sphinx 3 is not supported by kerneldoc, we probably should apply
>> a patch like
>>
>> https://www.spinics.net/lists/linux-doc/msg83277.html
> 
> We already have Sphinx 3.x hacks inside our fork of kernel-doc,
> see commit 152d1967f650 ("kernel-doc: Use c:struct for Sphinx 3.0
> and later").
> 
> If we want to keep deviating from upstream kernel-doc, the
> following patch seems to work.  Do we want to?
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 40ad782e342..03b49380426 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -838,6 +838,13 @@ sub output_function_rst(%) {
>       $lineprefix = "";
>       output_highlight_rst($args{'purpose'});
>       $start = "\n\n**Syntax**\n\n  ``";
> +    } elsif ($args{'functiontype'} eq "") {
> +     # this is a macro, Sphinx 3.x requires c:macro::
> +     if ((split(/\./, $sphinx_version))[0] >= 3) {
> +             print ".. c:macro:: ";
> +     } else {
> +             print ".. c:function:: ";
> +     }
>      } else {
>       print ".. c:function:: ";
>      }
>>
>> Paolo
>>
> 

I can try sending these to upstream Linux, too.

Paolo