Re: [for-5.0] docs: Require Sphinx 1.6 or better

[Daniel P . Berrangé]

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