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

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

Em Mon, 21 Sep 2020 23:26:39 +0100
Matthew Wilcox <willy@infradead.org> escreveu:

> 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?
> 
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#c-roles

I wouldn't mind converting the media books to use 3.0 style if
they work as expected.

Yet, if we convert, we need to change the minimal version requirement
to follow it. 
Sphinx 3.x is still too new. I bet distros don't bring it yet.

Ok, the default procedure is to pick it using pip or venv. So,
no bit issue, IMHO.

Also, as Jon mentioned, it takes about twice the time for the
doc build.

Not sure if it is worth.


Thanks,
Mauro