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

From: Eduardo Habkost <ehabkost@redhat.com>
To: Paolo Bonzini <pbonzini@redhat.com>
Cc: "Michal Prívozník" <mprivozn@redhat.com>,
	qemu-devel@nongnu.org, "Peter Maydell" <peter.maydell@linaro.org>
Subject: Re: [PULL v8 00/86] Misc QEMU patches for 2020-09-24
Date: Fri, 2 Oct 2020 14:24:57 -0400	[thread overview]
Message-ID: <20201002182457.GE7303@habkost.net> (raw)
In-Reply-To: <5c9a0783-f7ea-7872-f5f4-44ba9e65a1b2@redhat.com>

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
> 

-- 
Eduardo


