tree 269401208bab2de6465d45009ed1d87f70a0f434
parent 152d1967f650f67b7ece3a5dda77d48069d72647
author Peter Maydell <peter.maydell@linaro.org> 1586868074 +0100
committer Peter Maydell <peter.maydell@linaro.org> 1586881178 +0100

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 <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>