Skip to contentSkip to conversation

Fix build issues with Sphinx development tree

PATCH Superseded Mauro Carvalho Chehab 1 participant 3 messages Oct 15, 2020 Documentation

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover Fix build issues with Sphinx development tree

This Sphinx pull:

	https://github.com/sphinx-doc/sphinx/pull/8313

Fixes the C domain name conflicts when both a function and an enum, struct or union have the same name. Those fixes will generate new C domain warnings if an enum is defined using :c:struct.

So, we need to use different tags for structs or union. Thankfully, such change is backward compatible with Shinx 3.x. The first patch address it.

The second patch fix an issue at conf.py.

While Sphinx 4.0 was not released yet, the Sphinx development branch is using 4.0.0 as its version. There is a small issue at the code that excludes some macros from functions, if Sphinx major version is > 3.

Mauro Carvalho Chehab (2):
scripts: kernel-doc: use :c:union when needed
sphinx: conf.py: properly handle Sphinx 4.0

 Documentation/conf.py | 2 +-
 scripts/kernel-doc    | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH 1/2 scripts: kernel-doc: use :c:union when needed

Sphinx C domain code after 3.2.1 will start complaning if :c:struct would be used for an union type:

.../Documentation/gpu/drm-kms-helpers:352: ../drivers/video/hdmi.c:851: WARNING: C 'identifier' cross-reference uses wrong tag: reference name is 'union hdmi_infoframe' but found name is 'struct hdmi_infoframe'. Full reference name is 'union hdmi_infoframe'. Full found name is 'struct hdmi_infoframe'.

So, let's address this issue too in advance, in order to avoid future issues.

---
 scripts/kernel-doc | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
scripts/kernel-doc +5 -1
index c8f6b11d5da1..99cd8418ff8a 100755
@@ -1092,7 +1092,11 @@ sub output_struct_rst(%) {
 	print "\n\n.. c:type:: " . $name . "\n\n";
     } else {
 	my $name = $args{'struct'};
-	print "\n\n.. c:struct:: " . $name . "\n\n";
+	if ($args{'type'} eq 'union') {
+	    print "\n\n.. c:union:: " . $name . "\n\n";
+	} else {
+	    print "\n\n.. c:struct:: " . $name . "\n\n";
+	}
     }
     print_lineno($declaration_start_line);
     $lineprefix = "   ";
Signature · 1 line
2.26.2
#2 lore raw

PATCH 2/2 sphinx: conf.py: properly handle Sphinx 4.0

In reply to Mauro Carvalho Chehab

One of the checks for Sphinx 3+ is broken, causing some C warnings to return back with Sphinx 4.0.x.

---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/conf.py +1 -1
index 4f5d15abd047..a92442e70211 100644
@@ -50,7 +50,7 @@ if major >= 3:
         support for Sphinx v3.0 and above is brand new. Be prepared for
         possible issues in the generated output.
         ''')
-    if minor > 0 or patch >= 2:
+    if (major > 3) or (minor > 0 or patch >= 2):
         # Sphinx c function parser is more pedantic with regards to type
         # checking. Due to that, having macros at c:function cause problems.
         # Those needed to be scaped by using c_id_attributes[] array
Signature · 1 line
2.26.2