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 <peter.maydell@linaro.org>
---
 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
-- 
2.20.1

On 4/14/20 5: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 <peter.maydell@linaro.org>
> ---
>  docs/conf.py | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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 <peter.maydell@linaro.org>
> ---
>  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 <jsnow@redhat.com>

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

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

On Wed, 15 Apr 2020 at 15:51, Daniel P. Berrangé <berrange@redhat.com> wrote:
> On Tue, Apr 14, 2020 at 01:41:14PM +0100, Peter Maydell wrote:
> > 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.

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

As described above, configure will fall back to "disable building
the docs", unless you passed it --enable-docs, in which case it
will fail with the useful indication:
 Warning: $sphinx_build exists but it is either too old or uses too
old a Python version

thanks
-- PMM