Marc-André Lureau <marcandre.lur...@redhat.com> 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 <marcandre.lur...@redhat.com> > --- > 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