Re: [PATCH RFC] Make the docs build "work" with Sphinx 3.x

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Tue, 22 Sep 2020 10:56:56 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 22 Sep 2020 10:23:46 +0300
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
> > > Should we be converting the kernel-doc script to output 3.0-style markup
> > > for structs?  
> > 
> > IIUC it's not backwards compatible with Sphinx pre-3.0, so you'd either
> > have to require Sphinx 3.0 or have kernel-doc emit both, depending on
> > the Sphinx version.
> 
> Certainly before requiring 3.0 we should, like, actually make it work with
> 3.0...  People with time to do that appear to be rather scarce at the
> moment, though.  I'll get to it eventually but I have a few other things
> on my plate as well.

Tried to build now with Sphinx 3.2.1. There are thousands of warnings:

	build succeeded, 3423 warnings.

Like those:

	Documentation/driver-api/basics.rst: WARNING: Duplicate C declaration, also defined in 'core-api/workqueue'.
	Declaration is 'unsigned long delay'.

And those:

	./include/uapi/linux/firewire-cdev.h:38: WARNING: Type must be either just a name or a typedef-like declaration.
	If just a name:
	  Error in declarator or parameters
	  Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
	    struct fw_cdev_event_iso_interrupt
	    ------^
	If typedef-like declaration:
	  Error in declarator or parameters
	  Invalid C declaration: Expected identifier in nested name. [error at 34]
	    struct fw_cdev_event_iso_interrupt
	    ----------------------------------^

If I'm not mistaken, one of the reasons why cdomain was added is
due to the duplicate C declaration.

-

I guess changing kernel-doc to produce Sphinx 3.x syntax and
raise the bar requiring 3.0 to be the minimal version would be
one alternative, but this won't solve the duplicated C declarations. 

Does Sphinx 3.x have some way to enable "local" C references?

Another one could be to make cdomain compatible with 3.x and
make it handle the differences. Not sure how easy/hard would be
to do that.

Thanks,
Mauro