[PATCH 0/2] Fix build issues with Sphinx development tree

[PATCH 0/2] Fix build issues with Sphinx development tree

[Mauro Carvalho Chehab]

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(-)

-- 
2.26.2

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

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c8f6b11d5da1..99cd8418ff8a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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 = "   ";
-- 
2.26.2

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

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 4f5d15abd047..a92442e70211 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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
-- 
2.26.2