From bb43ee6c4f32026d911cba2db570847fabbfa7a4 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Tue, 25 Feb 2020 10:45:13 +0000 Subject: docs: Move qemu-option-trace.rst.inc to docs/ The qemu-option-trace.rst.inc file contains a rST documentation fragment which describes trace options common to qemu-nbd and qemu-img. We put this file into interop/, but we'd like to move the qemu-nbd and qemu-img files into the tools/ manual. We could move the .rst.inc file along with them, but we're eventually going to want to use it for the main QEMU binary options documentation too, and that will be in system/. So move qemu-option-trace.rst.inc to the top-level docs/ directory, where all these files can include it via .. include:: ../qemu-option-trace.rst.inc This does have the slight downside that we now need to explicitly tell Make which manuals use this file rather than relying on a wildcard for all .rst.inc in the manual. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson Acked-by: Paolo Bonzini Message-id: 20200217155415.30949-3-peter.maydell@linaro.org --- Makefile | 5 ++--- docs/interop/qemu-img.rst | 2 +- docs/interop/qemu-nbd.rst | 2 +- docs/interop/qemu-option-trace.rst.inc | 30 ------------------------------ docs/qemu-option-trace.rst.inc | 30 ++++++++++++++++++++++++++++++ 5 files changed, 34 insertions(+), 35 deletions(-) delete mode 100644 docs/interop/qemu-option-trace.rst.inc create mode 100644 docs/qemu-option-trace.rst.inc diff --git a/Makefile b/Makefile index c4c2eba..4a27be1 100644 --- a/Makefile +++ b/Makefile @@ -1049,7 +1049,6 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ - $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py # Macro to write out the rule and dependencies for building manpages # Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps]) @@ -1063,7 +1062,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1078,7 +1077,7 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(call define-manpage-rule,interop,\ qemu-ga.8 qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\ virtiofsd.1 virtfs-proxy-helper.1,\ - $(SRC_PATH)/qemu-img-cmds.hx) + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc) $(call define-manpage-rule,system,qemu-block-drivers.7) diff --git a/docs/interop/qemu-img.rst b/docs/interop/qemu-img.rst index 5f40137..0080f83 100644 --- a/docs/interop/qemu-img.rst +++ b/docs/interop/qemu-img.rst @@ -34,7 +34,7 @@ Standard options: .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] - .. include:: qemu-option-trace.rst.inc + .. include:: ../qemu-option-trace.rst.inc The following commands are supported: diff --git a/docs/interop/qemu-nbd.rst b/docs/interop/qemu-nbd.rst index e548403..667861c 100644 --- a/docs/interop/qemu-nbd.rst +++ b/docs/interop/qemu-nbd.rst @@ -188,7 +188,7 @@ driver options if ``--image-opts`` is specified. .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] - .. include:: qemu-option-trace.rst.inc + .. include:: ../qemu-option-trace.rst.inc Examples -------- diff --git a/docs/interop/qemu-option-trace.rst.inc b/docs/interop/qemu-option-trace.rst.inc deleted file mode 100644 index 23cfcb4..0000000 --- a/docs/interop/qemu-option-trace.rst.inc +++ /dev/null @@ -1,30 +0,0 @@ -.. - The contents of this file must be kept in sync with qemu-option-trace.texi - until all the users of the texi file have been converted to rst and - the texi file can be removed. - -Specify tracing options. - -.. option:: [enable=]PATTERN - - Immediately enable events matching *PATTERN* - (either event name or a globbing pattern). This option is only - available if QEMU has been compiled with the ``simple``, ``log`` - or ``ftrace`` tracing backend. To specify multiple events or patterns, - specify the :option:`-trace` option multiple times. - - Use :option:`-trace help` to print a list of names of trace points. - -.. option:: events=FILE - - Immediately enable events listed in *FILE*. - The file must contain one event name (as listed in the ``trace-events-all`` - file) per line; globbing patterns are accepted too. This option is only - available if QEMU has been compiled with the ``simple``, ``log`` or - ``ftrace`` tracing backend. - -.. option:: file=FILE - - Log output traces to *FILE*. - This option is only available if QEMU has been compiled with - the ``simple`` tracing backend. diff --git a/docs/qemu-option-trace.rst.inc b/docs/qemu-option-trace.rst.inc new file mode 100644 index 0000000..23cfcb4 --- /dev/null +++ b/docs/qemu-option-trace.rst.inc @@ -0,0 +1,30 @@ +.. + The contents of this file must be kept in sync with qemu-option-trace.texi + until all the users of the texi file have been converted to rst and + the texi file can be removed. + +Specify tracing options. + +.. option:: [enable=]PATTERN + + Immediately enable events matching *PATTERN* + (either event name or a globbing pattern). This option is only + available if QEMU has been compiled with the ``simple``, ``log`` + or ``ftrace`` tracing backend. To specify multiple events or patterns, + specify the :option:`-trace` option multiple times. + + Use :option:`-trace help` to print a list of names of trace points. + +.. option:: events=FILE + + Immediately enable events listed in *FILE*. + The file must contain one event name (as listed in the ``trace-events-all`` + file) per line; globbing patterns are accepted too. This option is only + available if QEMU has been compiled with the ``simple``, ``log`` or + ``ftrace`` tracing backend. + +.. option:: file=FILE + + Log output traces to *FILE*. + This option is only available if QEMU has been compiled with + the ``simple`` tracing backend. -- cgit v1.1