Em Wed, 23 Sep 2020 11:01:06 +0200 Mauro Carvalho Chehab <mchehab@xxxxxxxxxx> escreveu: > Em Tue, 22 Sep 2020 10:56:56 -0600 > Jonathan Corbet <corbet@xxxxxxx> escreveu: > > > On Tue, 22 Sep 2020 10:23:46 +0300 > > Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> 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. Ok, I checked the code of cdomain.py. It sounds that Markus tried to make cdomain compatible with Sphinx 3.x[1]: https://github.com/return42/linuxdoc/commit/48f09de2aff80169b7b9be5b0f2431ad8954e5cc [1] Yet, he ended disabling cdomain.py at his latest commit there: https://github.com/return42/linuxdoc/commit/70673dcf69e705e08d81f53794895dc15c4920b3#diff-40ccfb63661f88fd819794047febd54d (Basically, if Sphinx > 3.0, the cdomain.py is just an alias for c.py) I was hoping that porting such change would be enough for docs to build with Sphinx 3.2, but it isn't[2]. It seems that the entire Cdomain code was re-written: https://github.com/sphinx-doc/sphinx/commit/0f49e30c51b5cc5055cda5b4b294c2dd9d1df573#r38750737 There are now some environment vars that are required. Some of them have things like: lastSymbol = self.env.temp_data['c:last_symbol'] # type: Symbol assert lastSymbol If those aren't found, Sphinx crashes. So, making anything that would be compatible with both Sphinx 2.x and Sphinx 3.x seems very painful. It sounds to me that we need to make a choice here about how to proceed. We have a few alternatives: 1) stick forever with Sphinx 2.x syntax. We may end needing to support a fork of Sphinx, if we follow this direction, as nobody currently fix bugs on older versions of Sphinx; 2) switch to use Sphinx 3.x c domains and drop support for version < 3.x; 3) copy the code from Sphinx 2.x c.py file into our cdomain.py, making it to work with both versions. We may have troubles with newer versions of Sphinx if we follow this path though. If someone has enough time, one alternative would be to do a a mix of (2) and (3) by first porting to Sphinx 3.x and then re-writing the code at cdomain.py for it to work as a "backport" of the Sphinx 3.x c domain. - Assuming that we would take (1), I suspect that changing kernel-doc to produce Sphinx 3 domain shouldn't be too hard, but I'm a little bit afraid of namespace collisions. There is a new namespace directive there, introduced on Sphinx 3.1: .. c:namespace:: scope specification We'll likely need to use things like these in order to avoid namespace collisions, meaning that the new minimal version would be 3.1. Btw, with regards to namespace, there are two alternatives: - the RST files that would need it would explicitly have such directive; - the kernel-doc script could have a new option "namespace". If found, kernel-doc would output the namespace directive. IMO, this is more elegant. In any case, "namespace" will break automarkup.py for symbols that won't use the "NULL" namespace. Not sure how to fix it. Comments? Thanks, Mauro [2] After Markus patch, I applied this change, to solve the issues with the number of rows at the items array: diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index f262586cd094..6f1524bbede5 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -160,7 +160,10 @@ class CObject(Base_CObject): 'duplicate C object description of %s, ' % name + 'other instance in ' + self.env.doc2path(inv[name][0]), line=self.lineno) - inv[name] = (self.env.docname, self.objtype) + if major <= 2: + inv[name] = (self.env.docname, self.objtype) + else: + inv[name] = (self.env.docname, targetname, self.objtype) indextext = self.get_index_text(name) if indextext:
