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

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

Em Wed, 23 Sep 2020 14:31:55 +0200
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Tue, 22 Sep 2020 10:23:46 +0300
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> 
> > On Mon, 21 Sep 2020, Matthew Wilcox <willy@infradead.org> wrote:  
> > > On Fri, Sep 04, 2020 at 10:29:25AM -0600, Jonathan Corbet wrote:    
> > >> +# cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
> > >> +# of the docs correctly, but not all.  Scream bloody murder but allow
> > >> +# the process to proceed; hopefully somebody will fix this properly soon.
> > >> +#
> > >> +if major >= 3:
> > >> +    sys.stderr.write('''WARNING: The kernel documentation build process
> > >> +	does not work correctly with Sphinx v3.0 and above.  Expect errors
> > >> +	in the generated output.    
> > >
> > > 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.  
> 
> Well, making kernel-doc to emit both may be not too hard, as it
> could be doing something like:

Hi Jani,

> 
> <snp
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 0a102d57437d..0605949db383 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -50,6 +50,7 @@ if major >= 3:
>  	does not work correctly with Sphinx v3.0 and above.  Expect errors
>  	in the generated output.
>  	''')
> +    tags.add('sphinx3')
>  else:
>      extensions.append('cdomain')
>  
> diff --git a/Documentation/userspace-api/media/v4l/v4l2.rst b/Documentation/userspace-api/media/v4l/v4l2.rst
> index ad7a2bf0cf26..5007f33a7920 100644
> --- a/Documentation/userspace-api/media/v4l/v4l2.rst
> +++ b/Documentation/userspace-api/media/v4l/v4l2.rst
> @@ -3,6 +3,10 @@
>  
>  .. _v4l2spec:
>  
> +.. only: sphinx3
> +
> +   .. c:namespace:: v4l_uAPI
> +
>  ############################
>  Part I - Video for Linux API
>  ############################
> @@ -416,3 +420,7 @@ Second draft, with corrections pointed out by Gerd Knorr.
>  
>  First draft, based on documentation by Bill Dirks and discussions on the
>  V4L mailing list.
> +
> +.. only: sphinx3
> +
> +   .. c:namespace:: NULL

I actually tried that, but this didn't work.

Btw, it is not that simple. It needs to convert also several other tags,
and some are in the middle of the tests.

So, even if this would work, a change like that will introduce lots
of "noise" at the docs.

The approach of adding support for c:namespace: at cdomain
(see the patchset I sent today) is a lot more cleaner.

Thanks,
Mauro