From ae2b48e84a6b954b56f3e68f5fd2cde3484422cd Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Mon, 30 Nov 2020 09:52:57 +0100 Subject: [PATCH] doc: allow building htmldoc with Sphinx 3+ Due to removed function c_funcptr_sig_re building with Sphinx 3 fails. With the patch building succeeds with a lot of warnings if the '-W' flag is removed from doc/Makefile. Most of the documentation is correct This follows the approach taken by the Linux kernel. Signed-off-by: Heinrich Schuchardt --- doc/conf.py | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 93250a6aee..ee7f201724 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,7 +36,34 @@ latex_engine = 'xelatex' # 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', 'kfigure'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure'] + +# +# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* +# of the docs correctly, but not all. +# +if major >= 3: + if (major > 3) or (minor > 0 or patch >= 2): + sys.stderr.write('''The build process with Sphinx 3+ is broken. +You will have to remove -W in doc/Makefile. +''') + # 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 escaped by using c_id_attributes[] array + c_id_attributes = [ + + # include/linux/compiler.h + "__maybe_unused", + + # include/efi.h + "EFIAPI", + + # include/efi_loader.h + "__efi_runtime", + ] + +else: + extensions.append('cdomain') # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): -- 2.39.5