Re: [PATCH 2/3] docs: Create stub system manual
On Wed, 22 Jan 2020 at 18:58, Alex Bennée wrote: > Peter Maydell writes: > > diff --git a/docs/index.html.in b/docs/index.html.in > > index 94eb782cf7e..573c543c02b 100644 > > --- a/docs/index.html.in > > +++ b/docs/index.html.in > > @@ -11,6 +11,7 @@ > > QMP Reference Manual > > Guest Agent Protocol > > Reference > > System Emulation > > Management and Interoperability Guide > > +System Emulation User's > > Guide > > System Emulation Guest > > Hardware Specifications > > > > > > > This didn't seem to make a difference on readthedocs so I assume this is > for different tooling? It's for when you build manuals via the makefile, in which case you get multiple separate Sphinx manuals and want a top level index that links to those and also to our legacy non-Sphinx docs. So it's what you'll see in the installed version of the docs if you do a 'make install'. thanks -- PMM
Re: [PATCH 2/3] docs: Create stub system manual
Peter Maydell writes: > On Thu, 16 Jan 2020 at 14:15, Peter Maydell wrote: >> >> We want a user-facing manual which contains system emulation >> documentation. Create an empty one which we can populate. >> >> Signed-off-by: Peter Maydell >> --- >> Makefile | 10 +- >> docs/system/conf.py | 15 +++ >> docs/system/index.rst | 16 >> 3 files changed, 40 insertions(+), 1 deletion(-) >> create mode 100644 docs/system/conf.py >> create mode 100644 docs/system/index.rst > > I think this may have crossed in the post with the > commit adding index.html.in. Anyway, here's the obvious > fixup, which I plan to squash into this patch without > doing a respin unless there's some other respin needed: > > diff --git a/docs/index.html.in b/docs/index.html.in > index 94eb782cf7e..573c543c02b 100644 > --- a/docs/index.html.in > +++ b/docs/index.html.in > @@ -11,6 +11,7 @@ > QMP Reference Manual > Guest Agent Protocol > Reference > System Emulation > Management and Interoperability Guide > +System Emulation User's > Guide > System Emulation Guest > Hardware Specifications > > This didn't seem to make a difference on readthedocs so I assume this is for different tooling? Anyway: Reviewed-by: Alex Bennée > > thanks > -- PMM -- Alex Bennée
Re: [PATCH 2/3] docs: Create stub system manual
On Thu, 16 Jan 2020 at 14:15, Peter Maydell wrote: > > We want a user-facing manual which contains system emulation > documentation. Create an empty one which we can populate. > > Signed-off-by: Peter Maydell > --- > Makefile | 10 +- > docs/system/conf.py | 15 +++ > docs/system/index.rst | 16 > 3 files changed, 40 insertions(+), 1 deletion(-) > create mode 100644 docs/system/conf.py > create mode 100644 docs/system/index.rst I think this may have crossed in the post with the commit adding index.html.in. Anyway, here's the obvious fixup, which I plan to squash into this patch without doing a respin unless there's some other respin needed: diff --git a/docs/index.html.in b/docs/index.html.in index 94eb782cf7e..573c543c02b 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -11,6 +11,7 @@ QMP Reference Manual Guest Agent Protocol Reference System Emulation Management and Interoperability Guide +System Emulation User's Guide System Emulation Guest Hardware Specifications thanks -- PMM
[PATCH 2/3] docs: Create stub system manual
We want a user-facing manual which contains system emulation
documentation. Create an empty one which we can populate.
Signed-off-by: Peter Maydell
---
Makefile | 10 +-
docs/system/conf.py | 15 +++
docs/system/index.rst | 16
3 files changed, 40 insertions(+), 1 deletion(-)
create mode 100644 docs/system/conf.py
create mode 100644 docs/system/index.rst
diff --git a/Makefile b/Makefile
index 7a8a50d8700..4372d0d1fbd 100644
--- a/Makefile
+++ b/Makefile
@@ -757,6 +757,7 @@ distclean: clean
$(call clean-manual,devel)
$(call clean-manual,interop)
$(call clean-manual,specs)
+ $(call clean-manual,system)
for d in $(TARGET_DIRS); do \
rm -rf $$d || exit 1 ; \
done
@@ -813,6 +814,7 @@ endef
install-sphinxdocs: sphinxdocs
$(call install-manual,interop)
$(call install-manual,specs)
+ $(call install-manual,system)
install-doc: $(DOCS) install-sphinxdocs
$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
@@ -1000,7 +1002,10 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
# and handles "don't rebuild things unless necessary" itself.
# The '.doctrees' files are cached information to speed this up.
.PHONY: sphinxdocs
-sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
$(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
+sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
+$(MANUAL_BUILDDIR)/interop/index.html \
+$(MANUAL_BUILDDIR)/specs/index.html \
+$(MANUAL_BUILDDIR)/system/index.html
# Canned command to build a single manual
# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
@@ -1022,6 +1027,9 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call
manual-deps,interop)
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
$(call build-manual,specs,html)
+$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
+ $(call build-manual,system,html)
+
$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
$(call build-manual,interop,man)
diff --git a/docs/system/conf.py b/docs/system/conf.py
new file mode 100644
index 000..6435b4d3f8e
--- /dev/null
+++ b/docs/system/conf.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file for the 'system' manual.
+#
+# This includes the top level conf file and then makes any necessary tweaks.
+import sys
+import os
+
+qemu_docdir = os.path.abspath("..")
+parent_config = os.path.join(qemu_docdir, "conf.py")
+exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
+
+# This slightly misuses the 'description', but is the best way to get
+# the manual title to appear in the sidebar.
+html_theme_options['description'] = u'System Emulation User''s Guide'
diff --git a/docs/system/index.rst b/docs/system/index.rst
new file mode 100644
index 000..ea8ea5fe3dc
--- /dev/null
+++ b/docs/system/index.rst
@@ -0,0 +1,16 @@
+.. This is the top level page for the 'system' manual.
+
+
+QEMU System Emulation User's Guide
+==
+
+This manual is the overall guide for users using QEMU
+for full system emulation (as opposed to user-mode emulation).
+This includes working with hypervisors such as KVM, Xen, Hax
+or Hypervisor.Framework.
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
--
2.20.1
