[PATCH RFC] Make the docs build "work" with Sphinx 3.x

[Jonathan Corbet <corbet@lwn.net>]

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.  The
problems affect primarily the media documentation where :name: is used.

This is not a great solution, but it at least allows the docs build to
proceed on systems running 3.x until somebody has the time to put together
a proper fix.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
It seems that much of what we have in cdomain.cpy isn't needed with 3.x,
though that has to be verified.  But the :name: extension is problematic.
That needs a hard look, it's guaranteed to be a hard thing to maintain
going forward and it would be nice if we could find a way to do without it.

Meanwhile, building the docs with Sphinx 3.2.1 takes nearly twice as long
as with 2.2.2.  Given that the process was not exactly fast before, this
is not a welcome change.  Sigh.

 Documentation/conf.py | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

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
-- 
2.26.2