[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 29/33] docs: Generate qemu.1 manpage with Sphinx
From: |
Peter Maydell |
Subject: |
[PULL 29/33] docs: Generate qemu.1 manpage with Sphinx |
Date: |
Fri, 6 Mar 2020 11:09:55 +0000 |
Generate the qemu.1 manpage using Sphinx; we do this with a new
top-level rst source file which is just the skeleton of the manpage
and which includes .rst.inc fragments where it needs to incorporate
sections from the larger HTML manuals.
Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Tested-by: Alex Bennée <address@hidden>
Message-id: address@hidden
---
Makefile | 10 ++++----
docs/system/conf.py | 2 ++
docs/system/qemu-manpage.rst | 45 ++++++++++++++++++++++++++++++++++++
3 files changed, 51 insertions(+), 6 deletions(-)
create mode 100644 docs/system/qemu-manpage.rst
diff --git a/Makefile b/Makefile
index f7d08997dbf..ef10b9a031d 100644
--- a/Makefile
+++ b/Makefile
@@ -344,7 +344,8 @@ MANUAL_BUILDDIR := docs
endif
ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-doc.txt qemu.1
+DOCS=qemu-doc.html qemu-doc.txt
+DOCS+=$(MANUAL_BUILDDIR)/system/qemu.1
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
@@ -856,7 +857,7 @@ install-doc: $(DOCS) install-sphinxdocs
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
ifdef CONFIG_POSIX
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
- $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
+ $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1
"$(DESTDIR)$(mandir)/man1"
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
"$(DESTDIR)$(mandir)/man7"
@@ -1082,7 +1083,7 @@ $(MANUAL_BUILDDIR)/user/index.html: $(call
manual-deps,user)
$(call define-manpage-rule,interop,qemu-ga.8)
-$(call define-manpage-rule,system,qemu-block-drivers.7 qemu-cpu-models.7)
+$(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7
qemu-cpu-models.7)
$(call define-manpage-rule,tools,\
qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
@@ -1109,9 +1110,6 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
@cp -p $< $@
-qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi
qemu-monitor-info.texi
-qemu.1: docs/system/qemu-option-trace.texi
-
html: qemu-doc.html docs/interop/qemu-qmp-ref.html
docs/interop/qemu-ga-ref.html sphinxdocs
info: qemu-doc.info docs/interop/qemu-qmp-ref.info
docs/interop/qemu-ga-ref.info
pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
diff --git a/docs/system/conf.py b/docs/system/conf.py
index 23cab3fb364..6251849fefc 100644
--- a/docs/system/conf.py
+++ b/docs/system/conf.py
@@ -17,6 +17,8 @@ html_theme_options['description'] = u'System Emulation
User''s Guide'
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
+ ('qemu-manpage', 'qemu', u'QEMU User Documentation',
+ ['Fabrice Bellard'], 1),
('qemu-block-drivers', 'qemu-block-drivers',
u'QEMU block drivers reference',
['Fabrice Bellard and the QEMU Project developers'], 7),
diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
new file mode 100644
index 00000000000..e9a25d0680f
--- /dev/null
+++ b/docs/system/qemu-manpage.rst
@@ -0,0 +1,45 @@
+:orphan:
+
+..
+ This file is the skeleton for the qemu.1 manpage. It mostly
+ should simply include the .rst.inc files corresponding to the
+ parts of the documentation that go in the manpage as well as the
+ HTML manual.
+
+Title
+=====
+
+Synopsis
+--------
+
+.. parsed-literal::
+
+ |qemu_system| [options] [disk_image]
+
+Description
+-----------
+
+.. include:: target-i386-desc.rst.inc
+
+Options
+-------
+
+disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
+not need a disk image.
+
+.. hxtool-doc:: qemu-options.hx
+
+.. include:: keys.rst.inc
+
+.. include:: mux-chardev.rst.inc
+
+Notes
+-----
+
+.. include:: device-url-syntax.rst.inc
+
+See also
+--------
+
+The HTML documentation of QEMU for more precise information and Linux
+user mode emulator invocation.
--
2.20.1
- [PULL 15/33] docs/system: Convert qemu-cpu-models.texi to rST, (continued)
- [PULL 15/33] docs/system: Convert qemu-cpu-models.texi to rST, Peter Maydell, 2020/03/06
- [PULL 21/33] hmp-commands-info.hx: Add rST documentation fragments, Peter Maydell, 2020/03/06
- [PULL 05/33] qemu-doc: split qemu-doc.texi in multiple files, Peter Maydell, 2020/03/06
- [PULL 18/33] docs/system: convert the documentation of deprecated features to rST., Peter Maydell, 2020/03/06
- [PULL 22/33] doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING, Peter Maydell, 2020/03/06
- [PULL 24/33] docs: Roll -prom-env and -g target-specific info into qemu-options.hx, Peter Maydell, 2020/03/06
- [PULL 23/33] docs: Roll semihosting option information into qemu-options.hx, Peter Maydell, 2020/03/06
- [PULL 20/33] hmp-commands.hx: Add rST documentation fragments, Peter Maydell, 2020/03/06
- [PULL 25/33] scripts/hxtool-conv: Archive script used in qemu-options.hx conversion, Peter Maydell, 2020/03/06
- [PULL 27/33] qemu-options.hx: Fix up the autogenerated rST, Peter Maydell, 2020/03/06
- [PULL 29/33] docs: Generate qemu.1 manpage with Sphinx,
Peter Maydell <=
- [PULL 19/33] docs/system: convert Texinfo documentation to rST, Peter Maydell, 2020/03/06
- [PULL 28/33] docs: Split out sections for the manpage into .rst.inc files, Peter Maydell, 2020/03/06
- [PULL 31/33] docs: Stop building qemu-doc, Peter Maydell, 2020/03/06
- [PULL 30/33] ui/cocoa.m: Update documentation file and pathname, Peter Maydell, 2020/03/06
- [PULL 26/33] qemu-options.hx: Add rST documentation fragments, Peter Maydell, 2020/03/06
- [PULL 32/33] docs: Remove old texinfo sources, Peter Maydell, 2020/03/06
- [PULL 33/33] *.hx: Remove all the STEXI/ETEXI blocks, Peter Maydell, 2020/03/06
- Re: [PULL 00/33] docs queue, no-reply, 2020/03/06
- Re: [PULL 00/33] docs queue, Peter Maydell, 2020/03/06
- Re: [PULL 00/33] docs queue, no-reply, 2020/03/06