Skip to content
  • Peter Maydell's avatar
    bf3f8573
    docs: Require Sphinx 1.6 or better · bf3f8573
    Peter Maydell authored
    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: default avatarPeter Maydell <peter.maydell@linaro.org>
    Reviewed-by: default avatarRichard Henderson <richard.henderson@linaro.org>
    bf3f8573
    docs: Require Sphinx 1.6 or better
    Peter Maydell authored
    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: default avatarPeter Maydell <peter.maydell@linaro.org>
    Reviewed-by: default avatarRichard Henderson <richard.henderson@linaro.org>
Loading