Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

On Tue, 5 Mar 2019 at 12:47, Peter Maydell <address@hidden> wrote:
>
> On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <address@hidden> wrote:
> >
> > Hi Peter,
> >
> > On 2/28/19 3:56 PM, Peter Maydell wrote:
> > > +# Sphinx builds all its documentation at once in one invocation
> > > +# and handles "don't rebuild things unless necessary" itself.
> > > +# The '.doctrees' files are cached information to speed this up.
> >
> > Can you add .doctrees to .gitignore?
>
> Since this was the only change request for this patchset,
> I plan to send out a pullreq containing it, with this folded
> into this patch:
>
> diff --git a/.gitignore b/.gitignore
> index b66b7725512..77522561b8e 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -1,3 +1,4 @@
> +/.doctrees
>  /config-devices.*
>  /config-all-devices.*
>  /config-all-disas.*

Testing on various hosts revealed that we have a problem on
hosts with ancient versions of sphinx that predate the 'alabaster'
theme, so the configure test needs to be smarter. The fixup is
the change below.

Are people OK with me squashing this in too, or have we
reached the point where it really ought to have a v3 sent out ?


diff --git a/configure b/configure
index f1f028340aa..47bf617fcc5 100755
--- a/configure
+++ b/configure
@@ -4589,9 +4589,20 @@ if compile_prog "" "" ; then
   syncfs=yes
 fi

+# Check we have a new enough version of sphinx-build
+has_sphinx_build() {
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx"
"$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has makeinfo && has pod2man && has sphinx-build; then
+  if has makeinfo && has pod2man && has_sphinx_build; then
     docs=yes
   else
     if test "$docs" = "yes" ; then
diff --git a/docs/conf.py b/docs/conf.py
index 0842d44e930..befbcc6c3e1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -48,7 +48,8 @@ except NameError:

 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# 1.3 is where the 'alabaster' theme was shipped with Sphinx.
+needs_sphinx = '1.3'

 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom


thanks
-- PMM