Fix build issues with Sphinx development tree
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
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
@@ -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
PATCH 2/2 sphinx: conf.py: properly handle Sphinx 4.0
In reply to Mauro Carvalho ChehabOne 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
@@ -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