Re: [Qemu-devel] [PATCH v5 17/17] build-sys: add qapi doc generation targets

[Markus Armbruster]

Marc-André Lureau <address@hidden> writes:

> Generate and install the man and html version of QAPI documentation.
>
> Add it also to optional pdf/dvi/info targets.
>
> Also support plain-text targets docs/qemu-ga-ref.txt & docs/qemu-qmp-ref.txt.
>
> Signed-off-by: Marc-André Lureau <address@hidden>
> ---
>  Makefile           | 56 
> +++++++++++++++++++++++++++++++++++++++++++++++-------
>  .gitignore         | 11 ++++++++++-
>  docs/qmp-intro.txt |  3 +--
>  3 files changed, 60 insertions(+), 10 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 3617736..cc1c46e 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -91,6 +91,8 @@ HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
>  
>  ifdef BUILD_DOCS
>  DOCS=qemu-doc.html qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
> +DOCS+=docs/qemu-qmp-ref.html docs/qemu-qmp-ref.7
> +DOCS+=docs/qemu-ga-ref.html docs/qemu-ga-ref.7
>  ifdef CONFIG_VIRTFS
>  DOCS+=fsdev/virtfs-proxy-helper.1
>  endif
> @@ -266,6 +268,7 @@ qemu-ga$(EXESUF): QEMU_CFLAGS += -I qga/qapi-generated
>  gen-out-type = $(subst .,-,$(suffix $@))
>  
>  qapi-py = $(SRC_PATH)/scripts/qapi.py $(SRC_PATH)/scripts/ordereddict.py
> +qapi-py += $(SRC_PATH)/scripts/qapi2texi.py
>  
>  qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h :\
>  $(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-types.py $(qapi-py)
> @@ -395,6 +398,11 @@ distclean: clean
>       rm -f qemu-doc.vr
>       rm -f config.log
>       rm -f linux-headers/asm
> +     rm -f qemu-ga-qapi.texi qemu-qapi.texi
> +     rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7
> +     rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt
> +     rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
> +     rm -f docs/qemu-qmp-ref.html docs/qemu-ga-ref.html

Missing: .dvi

>       for d in $(TARGET_DIRS); do \
>       rm -rf $$d || exit 1 ; \
>          done
> @@ -431,9 +439,12 @@ endif
>  install-doc: $(DOCS)
>       $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
>       $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
> +     $(INSTALL_DATA) docs/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"

Personally, I'd install .txt along with .html, because the .txt is
perfectly legible, and plain text is easier to read in some situations.
We don't do that for qemu-doc, though.

>  ifdef CONFIG_POSIX
>       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
>       $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
> +     $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
> +     $(INSTALL_DATA) docs/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
>  ifneq ($(TOOLS),)
>       $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
>       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
> @@ -441,6 +452,8 @@ ifneq ($(TOOLS),)
>  endif
>  ifneq (,$(findstring qemu-ga,$(TOOLS)))
>       $(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
> +     $(INSTALL_DATA) docs/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
> +     $(INSTALL_DATA) docs/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
>  endif
>  endif
>  ifdef CONFIG_VIRTFS
> @@ -528,9 +541,9 @@ ui/console-gl.o: $(SRC_PATH)/ui/console-gl.c \
>       ui/shader/texture-blit-vert.h ui/shader/texture-blit-frag.h
>  
>  # documentation
> -MAKEINFO=makeinfo
> +MAKEINFO=makeinfo -D 'VERSION $(VERSION)'
>  MAKEINFOFLAGS=--no-headers --no-split --number-sections
> -TEXIFLAG=$(if $(V),,--quiet)
> +TEXIFLAG=$(if $(V),,--quiet) --command='@set VERSION $(VERSION)'
>  %.dvi: %.texi
>       $(call quiet-command,texi2dvi $(TEXIFLAG) -I . $<,"GEN","$@")
>  

Defines variable VERSION for all .texi, not just qemu-*-ref.texi, for
simplicity.  Works for me.

> @@ -542,7 +555,11 @@ TEXIFLAG=$(if $(V),,--quiet)
>       $(call quiet-command,$(MAKEINFO) $< -o $@,"GEN","$@")
>  
>  %.pdf: %.texi
> -     $(call quiet-command,texi2pdf $(TEXIFLAG) -I . $<,"GEN","$@")
> +     $(call quiet-command,texi2pdf $(TEXIFLAG) -I . $< -o $@,"GEN","$@")

I guess this simply makes the default implicit.  Okay.

> +
> +%.txt: %.texi
> +     $(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --plaintext 
> $< -o $@,\
> +     "  GEN   $@")

    $ make docs/qemu-qmp-ref.txt
        GEN   docs/qemu-qmp-ref.txt 
    Negative repeat count does nothing at 
/usr/share/texinfo/Texinfo/Convert/Line.pm line 128.
    Negative repeat count does nothing at 
/usr/share/texinfo/Texinfo/Convert/Line.pm line 128.
    Negative repeat count does nothing at 
/usr/share/texinfo/Texinfo/Convert/Line.pm line 128.

Could be something wrong with my system.  The result looks okay to me
all the same.

>  
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>       $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > 
> $@,"GEN","$@")
> @@ -556,6 +573,12 @@ qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx 
> $(SRC_PATH)/scripts/hxt
>  qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool
>       $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > 
> $@,"GEN","$@")
>  
> +qemu-qapi.texi: $(qapi-modules) $(qapi-py)
> +     $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > 
> $@,"GEN" "$@")
> +
> +qemu-ga-qapi.texi: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py)
> +     $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > 
> $@,"GEN","$@")
> +
>  qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi 
> qemu-monitor-info.texi
>       $(call quiet-command, \
>         perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \
> @@ -587,16 +610,35 @@ qemu-ga.8: qemu-ga.texi
>         $(POD2MAN) --section=8 --center=" " --release=" " qemu-ga.pod > $@, \
>         "GEN","$@")
>  
> -dvi: qemu-doc.dvi
> -html: qemu-doc.html
> -info: qemu-doc.info
> -pdf: qemu-doc.pdf
> +docs/qemu-qmp-ref.7:
> +     $(call quiet-command, \
> +      perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-qmp-ref.pod && \
> +      $(POD2MAN) --section=7 --center=" " --release=" " qemu-qmp-ref.pod > 
> $@, \
> +      "GEN","$@")
> +
> +docs/qemu-ga-ref.7:
> +     $(call quiet-command, \
> +      perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-ga-ref.pod && \
> +      $(POD2MAN) --section=7 --center=" " --release=" " qemu-ga-ref.pod > 
> $@, \
> +      "GEN","$@")

Recipe duplicated.  Would the following work?

   docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7:
        $(call quiet-command, \
         perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< $(@:.7=.pod) && \
         $(POD2MAN) --section=7 --center=" " --release=" " $(@:.7=.pod) > $@, \
         "GEN","$@")

Hmm, the recipe is duplicated many times over elsewhere already.
Nevermind, unless you genuinely want to clean that up.

> +
> +dvi: qemu-doc.dvi docs/qemu-qmp-ref.dvi docs/qemu-ga-ref.dvi
> +html: qemu-doc.html docs/qemu-qmp-ref.html docs/qemu-ga-ref.html
> +info: qemu-doc.info docs/qemu-qmp-ref.info docs/qemu-ga-ref.info
> +pdf: qemu-doc.pdf docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf

Would a txt target make sense?

>  
>  qemu-doc.dvi qemu-doc.html qemu-doc.info qemu-doc.pdf: \
>       qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
>       qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
>       qemu-monitor-info.texi
>  
> +docs/qemu-ga-ref.dvi docs/qemu-ga-ref.html docs/qemu-ga-ref.info 
> docs/qemu-ga-ref.pdf docs/qemu-ga-ref.txt docs/qemu-ga-ref.7: \
> +docs/qemu-ga-ref.texi qemu-ga-qapi.texi
> +
> +docs/qemu-qmp-ref.dvi docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info 
> docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7: \
> +docs/qemu-qmp-ref.texi qemu-qapi.texi
> +
> +
>  ifdef CONFIG_WIN32
>  
>  INSTALLER = qemu-setup-$(VERSION)$(EXESUF)
> diff --git a/.gitignore b/.gitignore
> index 3d7848c..d0905c3 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -39,7 +39,7 @@
>  /qmp-introspect.[ch]
>  /qmp-marshal.c
>  /qemu-doc.html
> -/qemu-doc.info
> +/qemu-doc.info*

I guess this is to cover the .info-1, .info-2, ... makeinfo produces
when it splits the output.  Separate patch, please.

Perhaps we should consider passing --no-split to makeinfo instead.  The
split I get seems rather pointless: .info-2 has a few indexes, all but
one empty, and .info-1 has all the rest, including some indexes.

>  /qemu-img
>  /qemu-nbd
>  /qemu-options.def
> @@ -109,6 +109,15 @@
>  /pc-bios/optionrom/kvmvapic.img
>  /pc-bios/s390-ccw/s390-ccw.elf
>  /pc-bios/s390-ccw/s390-ccw.img
> +/docs/qemu-ga-ref.html
> +/docs/qemu-ga-ref.txt
> +/docs/qemu-qmp-ref.html
> +/docs/qemu-qmp-ref.txt
> +docs/qemu-ga-ref.info*
> +docs/qemu-qmp-ref.info*
> +/qemu-ga-qapi.texi
> +/qemu-qapi.texi
> +*.tps
>  .stgit-*
>  cscope.*
>  tags
> diff --git a/docs/qmp-intro.txt b/docs/qmp-intro.txt
> index f6a3a03..60deafb 100644
> --- a/docs/qmp-intro.txt
> +++ b/docs/qmp-intro.txt
> @@ -16,8 +16,7 @@ QMP is JSON[1] based and features the following:
>  For detailed information on QMP's usage, please, refer to the following 
> files:
>  
>  o qmp-spec.txt      QEMU Machine Protocol current specification
> -o qmp-commands.txt  QMP supported commands (auto-generated at build-time)
> -o qmp-events.txt    List of available asynchronous events
> +o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at 
> build-time)
>  
>  [1] http://www.json.org