On 3/13/20 12:36 PM, Peter Maydell wrote:
> Raise ConfigError rather than VersionRequirementError when we detect
> that the Python being used by Sphinx is too old.
>
> Currently the way we flag the Python version problem up to the user
> causes Sphinx to print an unnecessary Python stack trace as well as
> the information about the problem; in most versions of Sphinx this is
> unavoidable.
>
> The upstream Sphinx developers kindly added a feature to allow
> conf.py to report errors to the user without the backtrace:
>
> https://github.com/sphinx-doc/sphinx/commit/be608ca2313fc08eb842f3dc19d0f5d2d8227d08
> but the exception type they chose for this was ConfigError.
>
> Switch to ConfigError, which won't make any difference with currently
> deployed Sphinx versions, but will be prettier one day when the user
> is using a Sphinx version with the new feature.
>
> Signed-off-by: Peter Maydell
> ---
> I don't think that commit is in a released Sphinx yet.
> ---
> docs/conf.py | 9 +
> 1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/docs/conf.py b/docs/conf.py
> index 960043cb860..87b5f07f589 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -29,14 +29,15 @@
> import os
> import sys
> import sphinx
> -from sphinx.errors import VersionRequirementError
> +from sphinx.errors import ConfigError
>
> # Make Sphinx fail cleanly if using an old Python, rather than obscurely
> # failing because some code in one of our extensions doesn't work there.
> -# Unfortunately this doesn't display very neatly (there's an unavoidable
> -# Python backtrace) but at least the information gets printed...
> +# In newer versions of Sphinx this will display nicely; in older versions
> +# Sphinx will also produce a Python backtrace but at least the information
> +# gets printed...
> if sys.version_info < (3,5):
> -raise VersionRequirementError(
> +raise ConfigError(
> "QEMU requires a Sphinx that uses Python 3.5 or better\n")
>
> # The per-manual conf.py will set qemu_docdir for a single-manual build;
>
When was ConfigError introduced, and what's our minimum Sphinx version?
(Hm, looks like it's not versioned, so I'll trust it's been around a while.)
Reviewed-by: John Snow
