| Message ID | 20161117155504.21843-18-marcandre.lureau@redhat.com |
|---|---|
| State | New |
| Headers | show |
Marc-André Lureau <marcandre.lureau@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.lureau@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
Hi On Fri, Nov 18, 2016 at 4:32 PM Markus Armbruster <armbru@redhat.com> wrote: > Marc-André Lureau <marcandre.lureau@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.lureau@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 > 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
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 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)" 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","$@") @@ -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","$@") + +%.txt: %.texi + $(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --plaintext $< -o $@,\ + " GEN $@") 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","$@") + +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 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* /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
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.lureau@redhat.com> --- Makefile | 56 +++++++++++++++++++++++++++++++++++++++++++++++------- .gitignore | 11 ++++++++++- docs/qmp-intro.txt | 3 +-- 3 files changed, 60 insertions(+), 10 deletions(-)