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.mayd...@linaro.org> > --- > docs/conf.py | 6 ++++-- > 1 file changed, 4 insertions(+), 2 deletions(-)
Reviewed-by: Richard Henderson <richard.hender...@linaro.org> r~
