On Tue, Apr 14, 2020 at 01:41:14PM +0100, Peter Maydell wrote: > 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.
What happens if you try to build QEMU on RHEL/CentOS-7 / Deb Stretch, with the new (unsatisfied) needs_sphinx version ? Does the build fail, or does configure automagically disable the building of docs ? > diff --git a/docs/conf.py b/docs/conf.py > index 7768611e89c..d6e173ef77b 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 > -- > 2.20.1 > > Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
