Em Wed, 23 Sep 2020 16:02:10 +0200 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
