From: Jonathan Corbet <corbet@lwn.net>
Date: Fri, 4 Sep 2020 16:13:45 +0000 (-0600)
Subject: Make the docs build "work" with Sphinx 3.x
X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=afde706afde2fea8a1dff84acaedac4f8dfe84b9;p=uclinux-h8%2Flinux.git

Make the docs build "work" with Sphinx 3.x

The Sphinx 3.x upgrade broke a number of things in our special "cdomain"
module that are not easy to fix.  For now, just disable that module for the
3.x build and put out a warning that the build will not be perfect.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---

diff --git a/Documentation/conf.py b/Documentation/conf.py
index c503188880d9..0a102d57437d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -36,10 +36,23 @@ needs_sphinx = '1.3'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel' ]
 
+#
+# cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
+# of the docs correctly, but not all.  Scream bloody murder but allow
+# the process to proceed; hopefully somebody will fix this properly soon.
+#
+if major >= 3:
+    sys.stderr.write('''WARNING: The kernel documentation build process
+	does not work correctly with Sphinx v3.0 and above.  Expect errors
+	in the generated output.
+	''')
+else:
+    extensions.append('cdomain')
+
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2