[PULL,3/3] docs/sphinx/kerneldoc.py: Honour --enable-werror

Commit Message

Laurent Vivier March 17, 2023, 2:18 p.m. UTC

From: Peter Maydell <[e-mail]>

Currently, the kerneldoc Sphinx plugin doesn't honour the
--enable-werror configure option, so its warnings are never fatal.
This is because although we do pass sphinx-build the -W switch, the
warnings from kerneldoc are produced by the scripts/kernel-doc script
directly and don't go through Sphinx's "emit a warning" function.

When --enable-werror is in effect, pass sphinx-build an extra
argument -Dkerneldoc_werror=1.  The kerneldoc plugin can then use
this to determine whether it should be passing the kernel-doc script
-Werror.

We do this because there is no documented mechanism for
a Sphinx plugin to determine whether sphinx-build was
passed -W or not; if one is provided then we can switch to
that at a later date:
https://github.com/sphinx-doc/sphinx/issues/11239

Signed-off-by: Peter Maydell <[e-mail]>
Reviewed-by: Thomas Huth <[e-mail]>
Message-Id: <[e-mail]>
Signed-off-by: Laurent Vivier <[e-mail]>
---
 docs/meson.build         | 2 +-
 docs/sphinx/kerneldoc.py | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

Patch

diff --git a/docs/meson.build b/docs/meson.build
index bb72c10ea8c5..f220800e3e59 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -7,7 +7,7 @@  if sphinx_build.found()
   SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q']
   # If we're making warnings fatal, apply this to Sphinx runs as well
   if get_option('werror')
-    SPHINX_ARGS += [ '-W' ]
+    SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
   endif
 
   # This is a bit awkward but works: create a trivial document and
diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
index bf442150165f..72c403a73798 100644
--- a/docs/sphinx/kerneldoc.py
+++ b/docs/sphinx/kerneldoc.py
@@ -74,6 +74,10 @@  def run(self):
         # Sphinx versions
         cmd += ['-sphinx-version', sphinx.__version__]
 
+        # Pass through the warnings-as-errors flag
+        if env.config.kerneldoc_werror:
+            cmd += ['-Werror']
+
         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
         export_file_patterns = []
 
@@ -167,6 +171,7 @@  def setup(app):
     app.add_config_value('kerneldoc_bin', None, 'env')
     app.add_config_value('kerneldoc_srctree', None, 'env')
     app.add_config_value('kerneldoc_verbosity', 1, 'env')
+    app.add_config_value('kerneldoc_werror', 0, 'env')
 
     app.add_directive('kernel-doc', KernelDocDirective)