From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Cc: "Paolo Bonzini" <pbonzini@redhat.com>,
"John Snow" <jsnow@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>
Subject: [for-5.0] docs: Require Sphinx 1.6 or better
Date: Tue, 14 Apr 2020 13:41:14 +0100 [thread overview]
Message-ID: <20200414124114.5363-1-peter.maydell@linaro.org> (raw)
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
next reply other threads:[~2020-04-14 12:42 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-04-14 12:41 Peter Maydell [this message]
2020-04-14 16:17 ` [for-5.0] docs: Require Sphinx 1.6 or better Richard Henderson
2020-04-15 13:33 ` John Snow
2020-04-15 14:50 ` Daniel P. Berrangé
2020-04-15 14:53 ` Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200414124114.5363-1-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=armbru@redhat.com \
--cc=jsnow@redhat.com \
--cc=pbonzini@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.