From bf3f857342b27e04871b22e3015fef5068a85723 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Tue, 14 Apr 2020 13:41:14 +0100 Subject: [PATCH] docs: Require Sphinx 1.6 or better Versions of Sphinx older than 1.6 can't build all of our documentation, because they are too picky about the syntax of the argument to the option:: directive; see Sphinx bugs #646, #3366: https://github.com/sphinx-doc/sphinx/issues/646 https://github.com/sphinx-doc/sphinx/issues/3366 Trying to build with a 1.4.x Sphinx fails with docs/system/images.rst:4: SEVERE: Duplicate ID: "cmdoption-qcow2-arg-encrypt" and a 1.5.x Sphinx fails with docs/system/invocation.rst:544: WARNING: Malformed option description '[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args" Update our needs_sphinx setting to indicate that we require at least 1.6. This will allow configure to fall back to "don't build the docs" rather than causing the build to fail entirely, which is probably what most users building on a host old enough to have such an old Sphinx would want; if they do want the docs then they'll have a useful indication of what they need to do (upgrade Sphinx!) rather than a confusing error message. In theory our distro support policy would suggest that we should support building on the Sphinx shipped in those distros, but: * EPEL7 has Sphinx 1.2.3 (which we've never supported!) * Debian Stretch has Sphinx 1.4.8 Trying to get our docs to work with Sphinx 1.4 is not tractable for the 5.0 release and I'm not sure it's worthwhile effort anyway; at least with this change the build as a whole now succeeds. Thanks to John Snow for doing the investigation and testing to confirm what Sphinx versions fail in what ways and what distros shipped what. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- docs/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7768611e89..d6e173ef77 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,8 +59,10 @@ sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) # If your documentation needs a minimal Sphinx version, state it here. # -# 1.3 is where the 'alabaster' theme was shipped with Sphinx. -needs_sphinx = '1.3' +# Sphinx 1.5 and earlier can't build our docs because they are too +# picky about the syntax of the argument to the option:: directive +# (see Sphinx bugs #646, #3366). +needs_sphinx = '1.6' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom