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

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

Em Wed, 23 Sep 2020 16:02:10 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Based on what it was described here:
> 
> 	https://github.com/sphinx-doc/sphinx/issues/7421
> 
> I worked on a RFC patch converting one of the media files
> (the CEC one, mentioned at the issue) in order to use the
> new Sphinx 3.1 C domain.
> 
> Yet, it sounds that the c:namespace is broken on Sphinx 3.2.1:
> 
> 	Documentation/userspace-api/media/cec/cec-func-close.rst:23: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fclose'.
> 	Declaration is 'int close( int fd )'.
> 	Documentation/userspace-api/media/cec/cec-func-close.rst: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fclose'.
> 	Declaration is 'int close(int fd)'.
> 	Documentation/userspace-api/media/cec/cec-func-close.rst: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fclose'.
> 	Declaration is 'int fd'.
> 	Documentation/userspace-api/media/cec/cec-func-open.rst:22: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fopen'.
> 	Declaration is 'int open( const char *device_name, int flags )'.
> 	Documentation/userspace-api/media/cec/cec-func-open.rst: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fopen'.
> 	Declaration is 'int open(const char *deviceName, int flags)'.
> 	Documentation/userspace-api/media/cec/cec-func-open.rst: WARNING: Duplicate C declaration, also defined in 'media/dvb/video-fopen'.
> 
> Or maybe it has to be defined on each individual .rst file that
> uses an specific domain?

Ok, I was able to get rid of the above warnings, after some discussions at:

	https://github.com/sphinx-doc/sphinx/issues/7421

In summary, the ".. c:namespace::" tag should be used on _every_ file
that uses a different namespace. For CEC, this is not too much,
but on v4l we have 249 files. Lots of them will require the usage of
the namespace directive.

I'm enclosing a patch with the minimal set of changes required to
make the CEC documentation compatible with Sphinx 3.1 and above.

Btw, according with Jakob, there was a bug that cause a run time
regression on Sphinx 3.2, affecting its performance:

	https://github.com/sphinx-doc/sphinx/issues/7421#issuecomment-697710707

Upstream Sphinx developers are working on a fix. So, maybe the
performance for an upcoming 3.2.2 will be similar to 2.x.

Jon,

Should we proceed enforcing version 3.1 to be the minimal one
required?

If so, I can take care of the conversion patches for the
media documents. I guess it should be easy to write a script that
would convert all the tags there to use the new notation.

I can also take a look at the kernel-doc issues.

-

If something has enough time to work at cdomain.py, we may
still have backward compatibility with versions 1.x/2.x
(support for 3.0.x would be a lot harder, IMHO), if cdomain.py 
would get support for at least those two tags:

	:c:expr:
	.. c:namespace::

Those two are the ones that are required to fix Sphinx 3.1+
support for the media docs (although there are other new
c domain tags that could also be interesting).

No idea wow easy/hard would be to add support for them over
there, as cdomain.py currently relies on the Sphinx 1.x/2.x
c domain code. I suspect that implementing support for namespace 
shouldn't be hard, as it internally does that already, but
using a different notation. Support for other tags can be
trickier.

I guess support for :c:expr:`foo()` should also be easy,
as this doesn't produce cross references. So, the code
could just convert this into something equivalent to:

	**``foo()``**

(e. g. into a bold monospaced font).

In any case, if we go to this direction, we'll be limited
to use a subset of the Sphinx 3.1 c domain notation.


Thanks,
Mauro