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

[Marc-André Lureau]

Hi

On Fri, Nov 18, 2016 at 4:32 PM Markus Armbruster <address@hidden> wrote:

> 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
>

I dropped it in a previous patch in the new series


>
> >       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.
>

Ok, let's install them all

>
> >  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.
>

I have the same warning, seems to be harmless though...


>
> >
> >  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.
>

Fixed it in the new series

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

added


>
> >
> >  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.
>
> ok


> 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.
>
> done


> >  /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
>
> --
Marc-André Lureau