diff mbox series

[v2,09/11] Makefile, configure: Support building rST documentation

Message ID 20190228145624.24885-10-peter.maydell@linaro.org
State Superseded
Headers show
Series Enable build and install of our rST docs | expand

Commit Message

Peter Maydell Feb. 28, 2019, 2:56 p.m. UTC 
Add support to our configure and makefile machinery for building
our rST docs into HTML files.

Building the documentation now requires that sphinx-build is
available; this seems better than allowing half the docs to
be built if it is not present but having half of them missing.
(In particular it means that assuming that distros configured with
--enable-docs they'll get a helpful error from configure telling
them the new build dependency.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---
 configure |  4 ++--
 Makefile  | 45 ++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 44 insertions(+), 5 deletions(-)

-- 
2.20.1

Comments

Philippe Mathieu-Daudé Feb. 28, 2019, 3:49 p.m. UTC | #1 
Hi Peter,

On 2/28/19 3:56 PM, Peter Maydell wrote:
> Add support to our configure and makefile machinery for building

> our rST docs into HTML files.

> 

> Building the documentation now requires that sphinx-build is

> available; this seems better than allowing half the docs to

> be built if it is not present but having half of them missing.

> (In particular it means that assuming that distros configured with

> --enable-docs they'll get a helpful error from configure telling

> them the new build dependency.)

> 

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

> ---

>  configure |  4 ++--

>  Makefile  | 45 ++++++++++++++++++++++++++++++++++++++++++---

>  2 files changed, 44 insertions(+), 5 deletions(-)

> 

> diff --git a/configure b/configure

> index 694088a4ec9..bf6850d4bd9 100755

> --- a/configure

> +++ b/configure

> @@ -4565,11 +4565,11 @@ fi

>  

>  # Check if tools are available to build documentation.

>  if test "$docs" != "no" ; then

> -  if has makeinfo && has pod2man; then

> +  if has makeinfo && has pod2man && has sphinx-build; then


Unrelated to your patch, I tried that on fresh Fedora image where no
python2 installed (on purpose). sphinx-build is not included in the
suggested python3-sphinx. Once python2-sphinx installed (which pull a
lot of py2 packages) I could test your series.

>      docs=yes

>    else

>      if test "$docs" = "yes" ; then

> -      feature_not_found "docs" "Install texinfo and Perl/perl-podlators"

> +      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"

>      fi

>      docs=no

>    fi

> diff --git a/Makefile b/Makefile

> index 7fa04e08212..d6b897be0bc 100644

> --- a/Makefile

> +++ b/Makefile

> @@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \

>  

>  include $(SRC_PATH)/tests/Makefile.include

>  

> -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules

> +all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules

>  

>  qemu-version.h: FORCE

>  	$(call quiet-command, \

> @@ -633,6 +633,14 @@ dist: qemu-$(VERSION).tar.bz2

>  qemu-%.tar.bz2:

>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"

>  

> +# Note that these commands assume that there are no HTML files in

> +# the docs subdir in the source tree! If there are then this will

> +# blow them away for an in-source-tree 'make clean'.

> +define clean-manual =

> +rm -rf docs/$1/_static

> +rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html

> +endef

> +

>  distclean: clean

>  	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi

>  	rm -f config-all-devices.mak config-all-disas.mak config.status

> @@ -653,6 +661,9 @@ distclean: clean

>  	rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html

>  	rm -f docs/qemu-block-drivers.7

>  	rm -f docs/qemu-cpu-models.7

> +	rm -f .doctrees

> +	$(call clean-manual,devel)

> +	$(call clean-manual,interop)

>  	for d in $(TARGET_DIRS); do \

>  	rm -rf $$d || exit 1 ; \

>          done

> @@ -686,7 +697,18 @@ else

>  BLOBS=

>  endif

>  

> -install-doc: $(DOCS)

> +define install-manual =

> +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done

> +for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done

> +endef

> +

> +# Note that we deliberately do not install the "devel" manual: it is

> +# for QEMU developers, and not interesting to our users.

> +.PHONY: install-sphinxdocs

> +install-sphinxdocs: sphinxdocs

> +	$(call install-manual,interop)


Again, not related to your patch, but 'make install-sphinxdocs' clone
libfdt + capstone, requires C compiler to build libfdt.a and C++ to
build libcapstone.a. Once both build we can generate the doc.

> +

> +install-doc: $(DOCS) install-sphinxdocs

>  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"

>  	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"

>  	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"

> @@ -837,6 +859,23 @@ docs/version.texi: $(SRC_PATH)/VERSION

>  %.pdf: %.texi docs/version.texi

>  	$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")

>  

> +# 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?

> +.PHONY: sphinxdocs

> +sphinxdocs: docs/devel/index.html docs/interop/index.html

> +

> +# Canned command to build a single manual

> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")

> +# We assume all RST files in the manual's directory are used in it

> +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py

> +

> +docs/devel/index.html: $(call manual-deps,devel)

> +	$(call build-manual,devel)

> +

> +docs/interop/index.html: $(call manual-deps,interop)

> +	$(call build-manual,interop)

> +

>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool

>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")

>  

> @@ -865,7 +904,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi

>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi

>  scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi

>  

> -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html

> +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs

>  info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info

>  pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf

>  txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt

> 


Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>


Thanks,

Phil.
Peter Maydell Feb. 28, 2019, 4:25 p.m. UTC | #2 
On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>

> Hi Peter,

>

> On 2/28/19 3:56 PM, Peter Maydell wrote:

> >  if test "$docs" != "no" ; then

> > -  if has makeinfo && has pod2man; then

> > +  if has makeinfo && has pod2man && has sphinx-build; then

>

> Unrelated to your patch, I tried that on fresh Fedora image where no

> python2 installed (on purpose). sphinx-build is not included in the

> suggested python3-sphinx. Once python2-sphinx installed (which pull a

> lot of py2 packages) I could test your series.


Yeah, Fedora gives the Python 3 version of the tool a silly name.
I'm told newer Fedora fix this.

> Again, not related to your patch, but 'make install-sphinxdocs' clone

> libfdt + capstone, requires C compiler to build libfdt.a and C++ to

> build libcapstone.a. Once both build we can generate the doc.


Yes, this sounds like an unrelated thing -- our makefiles
sometimes does more work than you expect because of some
things that we do up front (like building anything in
GENERATED_FILES, or doing this subdirs stuff). You can see
that sometimes when you do 'make clean' and it builds a
bunch of stuff before deleting it.

> > +# 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?


Sure. I tend to forget about this because I never do in-tree
builds, so anything in the build directory doesn't show up
in git status separately.

> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>


Thanks for the review.

-- PMM
Peter Maydell March 5, 2019, 12:47 p.m. UTC | #3 
On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> 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.*

thanks
-- PMM
Peter Maydell March 5, 2019, 3:24 p.m. UTC | #4 
On Tue, 5 Mar 2019 at 12:47, Peter Maydell <peter.maydell@linaro.org> wrote:
>

> On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> 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
Paolo Bonzini March 6, 2019, 10:53 a.m. UTC | #5 
On 05/03/19 16:24, Peter Maydell wrote:
> On Tue, 5 Mar 2019 at 12:47, Peter Maydell <peter.maydell@linaro.org> wrote:

>>

>> On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> 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 ?


Nah, go ahead.

Paolo
diff mbox series

Patch

diff --git a/configure b/configure
index 694088a4ec9..bf6850d4bd9 100755
--- a/configure
+++ b/configure
@@ -4565,11 +4565,11 @@  fi
 
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has makeinfo && has pod2man; then
+  if has makeinfo && has pod2man && has sphinx-build; then
     docs=yes
   else
     if test "$docs" = "yes" ; then
-      feature_not_found "docs" "Install texinfo and Perl/perl-podlators"
+      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
     fi
     docs=no
   fi
diff --git a/Makefile b/Makefile
index 7fa04e08212..d6b897be0bc 100644
--- a/Makefile
+++ b/Makefile
@@ -388,7 +388,7 @@  dummy := $(call unnest-vars,, \
 
 include $(SRC_PATH)/tests/Makefile.include
 
-all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules
 
 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -633,6 +633,14 @@  dist: qemu-$(VERSION).tar.bz2
 qemu-%.tar.bz2:
 	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
 
+# Note that these commands assume that there are no HTML files in
+# the docs subdir in the source tree! If there are then this will
+# blow them away for an in-source-tree 'make clean'.
+define clean-manual =
+rm -rf docs/$1/_static
+rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
+endef
+
 distclean: clean
 	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
 	rm -f config-all-devices.mak config-all-disas.mak config.status
@@ -653,6 +661,9 @@  distclean: clean
 	rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
 	rm -f docs/qemu-block-drivers.7
 	rm -f docs/qemu-cpu-models.7
+	rm -f .doctrees
+	$(call clean-manual,devel)
+	$(call clean-manual,interop)
 	for d in $(TARGET_DIRS); do \
 	rm -rf $$d || exit 1 ; \
         done
@@ -686,7 +697,18 @@  else
 BLOBS=
 endif
 
-install-doc: $(DOCS)
+define install-manual =
+for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
+for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
+endef
+
+# Note that we deliberately do not install the "devel" manual: it is
+# for QEMU developers, and not interesting to our users.
+.PHONY: install-sphinxdocs
+install-sphinxdocs: sphinxdocs
+	$(call install-manual,interop)
+
+install-doc: $(DOCS) install-sphinxdocs
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
@@ -837,6 +859,23 @@  docs/version.texi: $(SRC_PATH)/VERSION
 %.pdf: %.texi docs/version.texi
 	$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")
 
+# 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.
+.PHONY: sphinxdocs
+sphinxdocs: docs/devel/index.html docs/interop/index.html
+
+# Canned command to build a single manual
+build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
+# We assume all RST files in the manual's directory are used in it
+manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
+
+docs/devel/index.html: $(call manual-deps,devel)
+	$(call build-manual,devel)
+
+docs/interop/index.html: $(call manual-deps,interop)
+	$(call build-manual,interop)
+
 qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
 
@@ -865,7 +904,7 @@  docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
 docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
 scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
 
-html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
+html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
 info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
 pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
 txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt