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

[John Snow]

On 4/14/20 8:41 AM, 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.
> 
> 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 <address@hidden>
> ---
>  docs/conf.py | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> 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
> 


Reviewed-by: John Snow <address@hidden>

Thanks for the patch, sorry for not responding more quickly!