diff mbox series

[3/3] docs: Move tools documentation to tools manual

Message ID 20200217155415.30949-4-peter.maydell@linaro.org (mailing list archive)
State New, archived
Headers show
Series docs: Create a 'tools' manual | expand

Commit Message

Peter Maydell Feb. 17, 2020, 3:54 p.m. UTC 
Move the following tools documentation files to the new tools manual:

 docs/interop/qemu-img.rst
 docs/interop/qemu-nbd.rst
 docs/interop/virtfs-proxy-helper.rst
 docs/interop/qemu-trace-stap.rst
 docs/interop/virtiofsd.rst

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile                                      | 34 ++++++++++---------
 docs/interop/conf.py                          | 12 -------
 docs/interop/index.rst                        |  5 ---
 docs/tools/conf.py                            | 17 ++++++++++
 docs/tools/index.rst                          |  6 ++++
 docs/{interop => tools}/qemu-img.rst          |  0
 docs/{interop => tools}/qemu-nbd.rst          |  0
 docs/{interop => tools}/qemu-trace-stap.rst   |  0
 .../virtfs-proxy-helper.rst                   |  0
 docs/{interop => tools}/virtiofsd.rst         |  0
 10 files changed, 41 insertions(+), 33 deletions(-)
 rename docs/{interop => tools}/qemu-img.rst (100%)
 rename docs/{interop => tools}/qemu-nbd.rst (100%)
 rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
 rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
 rename docs/{interop => tools}/virtiofsd.rst (100%)

Comments

Dr. David Alan Gilbert Feb. 17, 2020, 6:24 p.m. UTC | #1 
* Peter Maydell (peter.maydell@linaro.org) wrote:
> Move the following tools documentation files to the new tools manual:
> 
>  docs/interop/qemu-img.rst
>  docs/interop/qemu-nbd.rst
>  docs/interop/virtfs-proxy-helper.rst
>  docs/interop/qemu-trace-stap.rst
>  docs/interop/virtiofsd.rst
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Would docs/tools be the right place for the virtiofsd security guide
(as previously posted there)?  It's not actually a manpage.

Dave
> ---
>  Makefile                                      | 34 ++++++++++---------
>  docs/interop/conf.py                          | 12 -------
>  docs/interop/index.rst                        |  5 ---
>  docs/tools/conf.py                            | 17 ++++++++++
>  docs/tools/index.rst                          |  6 ++++
>  docs/{interop => tools}/qemu-img.rst          |  0
>  docs/{interop => tools}/qemu-nbd.rst          |  0
>  docs/{interop => tools}/qemu-trace-stap.rst   |  0
>  .../virtfs-proxy-helper.rst                   |  0
>  docs/{interop => tools}/virtiofsd.rst         |  0
>  10 files changed, 41 insertions(+), 33 deletions(-)
>  rename docs/{interop => tools}/qemu-img.rst (100%)
>  rename docs/{interop => tools}/qemu-nbd.rst (100%)
>  rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
>  rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
>  rename docs/{interop => tools}/virtiofsd.rst (100%)
> 
> diff --git a/Makefile b/Makefile
> index 886d4299d54..7a9c682a2c0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -345,11 +345,11 @@ endif
>  
>  ifdef BUILD_DOCS
>  DOCS=qemu-doc.html qemu-doc.txt qemu.1
> -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1
> -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
> +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
> +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
>  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
>  ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> -DOCS+=$(MANUAL_BUILDDIR)/interop/virtiofsd.1
> +DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1
>  endif
>  DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
>  DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
> @@ -357,10 +357,10 @@ DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qe
>  DOCS+=docs/qemu-cpu-models.7
>  DOCS+=$(MANUAL_BUILDDIR)/index.html
>  ifdef CONFIG_VIRTFS
> -DOCS+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1
> +DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
>  endif
>  ifdef CONFIG_TRACE_SYSTEMTAP
> -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
> +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1
>  endif
>  else
>  DOCS=
> @@ -848,12 +848,12 @@ ifdef CONFIG_POSIX
>  	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
>  	$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
>  ifeq ($(CONFIG_TOOLS),y)
> -	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
> -	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
>  endif
>  ifdef CONFIG_TRACE_SYSTEMTAP
> -	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  ifneq (,$(findstring qemu-ga,$(TOOLS)))
>  	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
> @@ -864,10 +864,10 @@ endif
>  endif
>  ifdef CONFIG_VIRTFS
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
> -	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> -	$(INSTALL_DATA) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> +	$(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
>  endif
>  
>  install-datadir:
> @@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
>  	$(call build-manual,interop,html)
>  
>  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> @@ -1058,16 +1058,18 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
>  $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
>  	$(call build-manual,system,html)
>  
> -$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools)
> +$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
>  	$(call build-manual,tools,html)
>  
> -$(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)/docs/qemu-option-trace.rst.inc)
> +$(call define-manpage-rule,interop,qemu-ga.8)
>  
>  $(call define-manpage-rule,system,qemu-block-drivers.7)
>  
> +$(call define-manpage-rule,tools,\
> +       qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
> +       virtiofsd.1 virtfs-proxy-helper.1,\
> +       $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc)
> +
>  $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
>  	@mkdir -p "$(MANUAL_BUILDDIR)"
>  	$(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
> diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> index b3cda17042c..42ce7e3d365 100644
> --- a/docs/interop/conf.py
> +++ b/docs/interop/conf.py
> @@ -19,16 +19,4 @@ html_theme_options['description'] = u'System Emulation Management and Interopera
>  man_pages = [
>      ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
>       ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
> -    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
> -     ['Fabrice Bellard'], 1),
> -    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
> -     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
> -    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> -     [], 1),
> -    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
> -     u'QEMU 9p virtfs proxy filesystem helper',
> -     ['M. Mohan Kumar'], 1),
> -    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
> -     ['Stefan Hajnoczi <stefanha@redhat.com>',
> -      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
>  ]
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index e8455b4270c..049387ac6de 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -18,10 +18,5 @@ Contents:
>     live-block-operations
>     pr-helper
>     qemu-ga
> -   qemu-img
> -   qemu-nbd
> -   qemu-trace-stap
>     vhost-user
>     vhost-user-gpu
> -   virtfs-proxy-helper
> -   virtiofsd
> diff --git a/docs/tools/conf.py b/docs/tools/conf.py
> index 56461110b9d..9052d17d6d4 100644
> --- a/docs/tools/conf.py
> +++ b/docs/tools/conf.py
> @@ -14,3 +14,20 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
>  # the manual title to appear in the sidebar.
>  html_theme_options['description'] = \
>      u'Tools Guide'
> +
> +# One entry per manual page. List of tuples
> +# (source start file, name, description, authors, manual section).
> +man_pages = [
> +    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
> +     ['Fabrice Bellard'], 1),
> +    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
> +     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
> +    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> +     [], 1),
> +    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
> +     u'QEMU 9p virtfs proxy filesystem helper',
> +     ['M. Mohan Kumar'], 1),
> +    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
> +     ['Stefan Hajnoczi <stefanha@redhat.com>',
> +      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> +]
> diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> index c5a4a13ec7a..232ce9f3e46 100644
> --- a/docs/tools/index.rst
> +++ b/docs/tools/index.rst
> @@ -9,3 +9,9 @@ Contents:
>  
>  .. toctree::
>     :maxdepth: 2
> +
> +   qemu-img
> +   qemu-nbd
> +   qemu-trace-stap
> +   virtfs-proxy-helper
> +   virtiofsd
> diff --git a/docs/interop/qemu-img.rst b/docs/tools/qemu-img.rst
> similarity index 100%
> rename from docs/interop/qemu-img.rst
> rename to docs/tools/qemu-img.rst
> diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
> similarity index 100%
> rename from docs/interop/qemu-nbd.rst
> rename to docs/tools/qemu-nbd.rst
> diff --git a/docs/interop/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst
> similarity index 100%
> rename from docs/interop/qemu-trace-stap.rst
> rename to docs/tools/qemu-trace-stap.rst
> diff --git a/docs/interop/virtfs-proxy-helper.rst b/docs/tools/virtfs-proxy-helper.rst
> similarity index 100%
> rename from docs/interop/virtfs-proxy-helper.rst
> rename to docs/tools/virtfs-proxy-helper.rst
> diff --git a/docs/interop/virtiofsd.rst b/docs/tools/virtiofsd.rst
> similarity index 100%
> rename from docs/interop/virtiofsd.rst
> rename to docs/tools/virtiofsd.rst
> -- 
> 2.20.1
> 
--
Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
Paolo Bonzini Feb. 17, 2020, 6:41 p.m. UTC | #2 
Il lun 17 feb 2020, 19:24 Dr. David Alan Gilbert <dgilbert@redhat.com> ha
scritto:

> * Peter Maydell (peter.maydell@linaro.org) wrote:
> > Move the following tools documentation files to the new tools manual:
> >
> >  docs/interop/qemu-img.rst
> >  docs/interop/qemu-nbd.rst
> >  docs/interop/virtfs-proxy-helper.rst
> >  docs/interop/qemu-trace-stap.rst
> >  docs/interop/virtiofsd.rst
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
> Would docs/tools be the right place for the virtiofsd security guide
> (as previously posted there)?  It's not actually a manpage.
>

Yes, I think it would.

Paolo


> Dave
> > ---
> >  Makefile                                      | 34 ++++++++++---------
> >  docs/interop/conf.py                          | 12 -------
> >  docs/interop/index.rst                        |  5 ---
> >  docs/tools/conf.py                            | 17 ++++++++++
> >  docs/tools/index.rst                          |  6 ++++
> >  docs/{interop => tools}/qemu-img.rst          |  0
> >  docs/{interop => tools}/qemu-nbd.rst          |  0
> >  docs/{interop => tools}/qemu-trace-stap.rst   |  0
> >  .../virtfs-proxy-helper.rst                   |  0
> >  docs/{interop => tools}/virtiofsd.rst         |  0
> >  10 files changed, 41 insertions(+), 33 deletions(-)
> >  rename docs/{interop => tools}/qemu-img.rst (100%)
> >  rename docs/{interop => tools}/qemu-nbd.rst (100%)
> >  rename docs/{interop => tools}/qemu-trace-stap.rst (100%)
> >  rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%)
> >  rename docs/{interop => tools}/virtiofsd.rst (100%)
> >
> > diff --git a/Makefile b/Makefile
> > index 886d4299d54..7a9c682a2c0 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -345,11 +345,11 @@ endif
> >
> >  ifdef BUILD_DOCS
> >  DOCS=qemu-doc.html qemu-doc.txt qemu.1
> > -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1
> > -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
> > +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
> > +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
> >  DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
> >  ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> > -DOCS+=$(MANUAL_BUILDDIR)/interop/virtiofsd.1
> > +DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1
> >  endif
> >  DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
> >  DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt
> docs/interop/qemu-qmp-ref.7
> > @@ -357,10 +357,10 @@ DOCS+=docs/interop/qemu-ga-ref.html
> docs/interop/qemu-ga-ref.txt docs/interop/qe
> >  DOCS+=docs/qemu-cpu-models.7
> >  DOCS+=$(MANUAL_BUILDDIR)/index.html
> >  ifdef CONFIG_VIRTFS
> > -DOCS+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1
> > +DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
> >  endif
> >  ifdef CONFIG_TRACE_SYSTEMTAP
> > -DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
> > +DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1
> >  endif
> >  else
> >  DOCS=
> > @@ -848,12 +848,12 @@ ifdef CONFIG_POSIX
> >       $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
> "$(DESTDIR)$(mandir)/man7"
> >       $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
> >  ifeq ($(CONFIG_TOOLS),y)
> > -     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1
> "$(DESTDIR)$(mandir)/man1"
> > +     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1
> "$(DESTDIR)$(mandir)/man1"
> >       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
> > -     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8
> "$(DESTDIR)$(mandir)/man8"
> > +     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-nbd.8
> "$(DESTDIR)$(mandir)/man8"
> >  endif
> >  ifdef CONFIG_TRACE_SYSTEMTAP
> > -     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
> "$(DESTDIR)$(mandir)/man1"
> > +     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1
> "$(DESTDIR)$(mandir)/man1"
> >  endif
> >  ifneq (,$(findstring qemu-ga,$(TOOLS)))
> >       $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8
> "$(DESTDIR)$(mandir)/man8"
> > @@ -864,10 +864,10 @@ endif
> >  endif
> >  ifdef CONFIG_VIRTFS
> >       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
> > -     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1
> "$(DESTDIR)$(mandir)/man1"
> > +     $(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
> "$(DESTDIR)$(mandir)/man1"
> >  endif
> >  ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
> > -     $(INSTALL_DATA) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> > +     $(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
> >  endif
> >
> >  install-datadir:
> > @@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> > +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
> >       $(call build-manual,interop,html)
> >
> >  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> > @@ -1058,16 +1058,18 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call
> manual-deps,specs)
> >  $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
> >       $(call build-manual,system,html)
> >
> > -$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools)
> > +$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools)
> $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> >       $(call build-manual,tools,html)
> >
> > -$(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)/docs/qemu-option-trace.rst.inc)
> > +$(call define-manpage-rule,interop,qemu-ga.8)
> >
> >  $(call define-manpage-rule,system,qemu-block-drivers.7)
> >
> > +$(call define-manpage-rule,tools,\
> > +       qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
> > +       virtiofsd.1 virtfs-proxy-helper.1,\
> > +       $(SRC_PATH)/qemu-img-cmds.hx
> $(SRC_PATH)/docs/qemu-option-trace.rst.inc)
> > +
> >  $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in
> qemu-version.h
> >       @mkdir -p "$(MANUAL_BUILDDIR)"
> >       $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
> > diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> > index b3cda17042c..42ce7e3d365 100644
> > --- a/docs/interop/conf.py
> > +++ b/docs/interop/conf.py
> > @@ -19,16 +19,4 @@ html_theme_options['description'] = u'System
> Emulation Management and Interopera
> >  man_pages = [
> >      ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
> >       ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
> > -    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
> > -     ['Fabrice Bellard'], 1),
> > -    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
> > -     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
> > -    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> > -     [], 1),
> > -    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
> > -     u'QEMU 9p virtfs proxy filesystem helper',
> > -     ['M. Mohan Kumar'], 1),
> > -    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system
> daemon',
> > -     ['Stefan Hajnoczi <stefanha@redhat.com>',
> > -      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> >  ]
> > diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> > index e8455b4270c..049387ac6de 100644
> > --- a/docs/interop/index.rst
> > +++ b/docs/interop/index.rst
> > @@ -18,10 +18,5 @@ Contents:
> >     live-block-operations
> >     pr-helper
> >     qemu-ga
> > -   qemu-img
> > -   qemu-nbd
> > -   qemu-trace-stap
> >     vhost-user
> >     vhost-user-gpu
> > -   virtfs-proxy-helper
> > -   virtiofsd
> > diff --git a/docs/tools/conf.py b/docs/tools/conf.py
> > index 56461110b9d..9052d17d6d4 100644
> > --- a/docs/tools/conf.py
> > +++ b/docs/tools/conf.py
> > @@ -14,3 +14,20 @@ exec(compile(open(parent_config, "rb").read(),
> parent_config, 'exec'))
> >  # the manual title to appear in the sidebar.
> >  html_theme_options['description'] = \
> >      u'Tools Guide'
> > +
> > +# One entry per manual page. List of tuples
> > +# (source start file, name, description, authors, manual section).
> > +man_pages = [
> > +    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
> > +     ['Fabrice Bellard'], 1),
> > +    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
> > +     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
> > +    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
> > +     [], 1),
> > +    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
> > +     u'QEMU 9p virtfs proxy filesystem helper',
> > +     ['M. Mohan Kumar'], 1),
> > +    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system
> daemon',
> > +     ['Stefan Hajnoczi <stefanha@redhat.com>',
> > +      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
> > +]
> > diff --git a/docs/tools/index.rst b/docs/tools/index.rst
> > index c5a4a13ec7a..232ce9f3e46 100644
> > --- a/docs/tools/index.rst
> > +++ b/docs/tools/index.rst
> > @@ -9,3 +9,9 @@ Contents:
> >
> >  .. toctree::
> >     :maxdepth: 2
> > +
> > +   qemu-img
> > +   qemu-nbd
> > +   qemu-trace-stap
> > +   virtfs-proxy-helper
> > +   virtiofsd
> > diff --git a/docs/interop/qemu-img.rst b/docs/tools/qemu-img.rst
> > similarity index 100%
> > rename from docs/interop/qemu-img.rst
> > rename to docs/tools/qemu-img.rst
> > diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
> > similarity index 100%
> > rename from docs/interop/qemu-nbd.rst
> > rename to docs/tools/qemu-nbd.rst
> > diff --git a/docs/interop/qemu-trace-stap.rst
> b/docs/tools/qemu-trace-stap.rst
> > similarity index 100%
> > rename from docs/interop/qemu-trace-stap.rst
> > rename to docs/tools/qemu-trace-stap.rst
> > diff --git a/docs/interop/virtfs-proxy-helper.rst
> b/docs/tools/virtfs-proxy-helper.rst
> > similarity index 100%
> > rename from docs/interop/virtfs-proxy-helper.rst
> > rename to docs/tools/virtfs-proxy-helper.rst
> > diff --git a/docs/interop/virtiofsd.rst b/docs/tools/virtiofsd.rst
> > similarity index 100%
> > rename from docs/interop/virtiofsd.rst
> > rename to docs/tools/virtiofsd.rst
> > --
> > 2.20.1
> >
> --
> Dr. David Alan Gilbert / dgilbert@redhat.com / Manchester, UK
>
>
Peter Maydell Feb. 17, 2020, 7:19 p.m. UTC | #3 
On Mon, 17 Feb 2020 at 18:41, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
>
>
> Il lun 17 feb 2020, 19:24 Dr. David Alan Gilbert <dgilbert@redhat.com> ha scritto:
>>
>> * Peter Maydell (peter.maydell@linaro.org) wrote:
>> > Move the following tools documentation files to the new tools manual:
>> >
>> >  docs/interop/qemu-img.rst
>> >  docs/interop/qemu-nbd.rst
>> >  docs/interop/virtfs-proxy-helper.rst
>> >  docs/interop/qemu-trace-stap.rst
>> >  docs/interop/virtiofsd.rst
>> >
>> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>>
>> Would docs/tools be the right place for the virtiofsd security guide
>> (as previously posted there)?  It's not actually a manpage.
>
> Yes, I think it would.

I agree. (IMHO) tools/ is not "things with manpages" (we have
manpages like qemu-block-drivers.7 that live in system/), it's
"documentation relating to standalone tools". It's just
coincidence (plus the fact that often the only bit of documentation
a standalone tool has is its manpage) that all the things
that got moved in this patchset happen to generate manpages.

thanks
-- PMM
diff mbox series

Patch

diff --git a/Makefile b/Makefile
index 886d4299d54..7a9c682a2c0 100644
--- a/Makefile
+++ b/Makefile
@@ -345,11 +345,11 @@  endif
 
 ifdef BUILD_DOCS
 DOCS=qemu-doc.html qemu-doc.txt qemu.1
-DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1
-DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
+DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
+DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
 ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
-DOCS+=$(MANUAL_BUILDDIR)/interop/virtiofsd.1
+DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1
 endif
 DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
@@ -357,10 +357,10 @@  DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qe
 DOCS+=docs/qemu-cpu-models.7
 DOCS+=$(MANUAL_BUILDDIR)/index.html
 ifdef CONFIG_VIRTFS
-DOCS+=$(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1
+DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
 endif
 ifdef CONFIG_TRACE_SYSTEMTAP
-DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1
+DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1
 endif
 else
 DOCS=
@@ -848,12 +848,12 @@  ifdef CONFIG_POSIX
 	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
 	$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
 ifeq ($(CONFIG_TOOLS),y)
-	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
+	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
-	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
+	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
 endif
 ifdef CONFIG_TRACE_SYSTEMTAP
-	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
+	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
 endif
 ifneq (,$(findstring qemu-ga,$(TOOLS)))
 	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
@@ -864,10 +864,10 @@  endif
 endif
 ifdef CONFIG_VIRTFS
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
-	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
+	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
 endif
 ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy)
-	$(INSTALL_DATA) docs/interop/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
+	$(INSTALL_DATA) docs/tools/virtiofsd.1 "$(DESTDIR)$(mandir)/man1"
 endif
 
 install-datadir:
@@ -1049,7 +1049,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 $(SRC_PATH)/docs/qemu-option-trace.rst.inc
+$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
 	$(call build-manual,interop,html)
 
 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1058,16 +1058,18 @@  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
 $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
 	$(call build-manual,system,html)
 
-$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools)
+$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
 	$(call build-manual,tools,html)
 
-$(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)/docs/qemu-option-trace.rst.inc)
+$(call define-manpage-rule,interop,qemu-ga.8)
 
 $(call define-manpage-rule,system,qemu-block-drivers.7)
 
+$(call define-manpage-rule,tools,\
+       qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
+       virtiofsd.1 virtfs-proxy-helper.1,\
+       $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc)
+
 $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
 	@mkdir -p "$(MANUAL_BUILDDIR)"
 	$(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index b3cda17042c..42ce7e3d365 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -19,16 +19,4 @@  html_theme_options['description'] = u'System Emulation Management and Interopera
 man_pages = [
     ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
      ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
-    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
-     ['Fabrice Bellard'], 1),
-    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
-     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
-    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
-     [], 1),
-    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
-     u'QEMU 9p virtfs proxy filesystem helper',
-     ['M. Mohan Kumar'], 1),
-    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
-     ['Stefan Hajnoczi <stefanha@redhat.com>',
-      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
 ]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index e8455b4270c..049387ac6de 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -18,10 +18,5 @@  Contents:
    live-block-operations
    pr-helper
    qemu-ga
-   qemu-img
-   qemu-nbd
-   qemu-trace-stap
    vhost-user
    vhost-user-gpu
-   virtfs-proxy-helper
-   virtiofsd
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 56461110b9d..9052d17d6d4 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -14,3 +14,20 @@  exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
 # the manual title to appear in the sidebar.
 html_theme_options['description'] = \
     u'Tools Guide'
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('qemu-img', 'qemu-img', u'QEMU disk image utility',
+     ['Fabrice Bellard'], 1),
+    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
+     ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
+    ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
+     [], 1),
+    ('virtfs-proxy-helper', 'virtfs-proxy-helper',
+     u'QEMU 9p virtfs proxy filesystem helper',
+     ['M. Mohan Kumar'], 1),
+    ('virtiofsd', 'virtiofsd', u'QEMU virtio-fs shared file system daemon',
+     ['Stefan Hajnoczi <stefanha@redhat.com>',
+      'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
+]
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index c5a4a13ec7a..232ce9f3e46 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -9,3 +9,9 @@  Contents:
 
 .. toctree::
    :maxdepth: 2
+
+   qemu-img
+   qemu-nbd
+   qemu-trace-stap
+   virtfs-proxy-helper
+   virtiofsd
diff --git a/docs/interop/qemu-img.rst b/docs/tools/qemu-img.rst
similarity index 100%
rename from docs/interop/qemu-img.rst
rename to docs/tools/qemu-img.rst
diff --git a/docs/interop/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
similarity index 100%
rename from docs/interop/qemu-nbd.rst
rename to docs/tools/qemu-nbd.rst
diff --git a/docs/interop/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst
similarity index 100%
rename from docs/interop/qemu-trace-stap.rst
rename to docs/tools/qemu-trace-stap.rst
diff --git a/docs/interop/virtfs-proxy-helper.rst b/docs/tools/virtfs-proxy-helper.rst
similarity index 100%
rename from docs/interop/virtfs-proxy-helper.rst
rename to docs/tools/virtfs-proxy-helper.rst
diff --git a/docs/interop/virtiofsd.rst b/docs/tools/virtiofsd.rst
similarity index 100%
rename from docs/interop/virtiofsd.rst
rename to docs/tools/virtiofsd.rst