| Message ID | 20200116141511.16849-3-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | convert qemu-nbd, qemu-block-drivers to rST | expand |
On Thu, 16 Jan 2020 at 14:15, Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> > --- > 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 @@ <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li> <li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li> <li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li> + <li><a href="system/index.html">System Emulation User's Guide</a></li> <li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li> </ul> </body> thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Thu, 16 Jan 2020 at 14:15, Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> >> --- >> 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 @@ > <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li> > <li><a href="qemu-ga-ref.html">Guest Agent Protocol > Reference</a></li> > <li><a href="interop/index.html">System Emulation > Management and Interoperability Guide</a></li> > + <li><a href="system/index.html">System Emulation User's > Guide</a></li> > <li><a href="specs/index.html">System Emulation Guest > Hardware Specifications</a></li> > </ul> > </body> This didn't seem to make a difference on readthedocs so I assume this is for different tooling? Anyway: Reviewed-by: Alex Bennée <alex.bennee@linaro.org> > > thanks > -- PMM
On Wed, 22 Jan 2020 at 18:58, Alex Bennée <alex.bennee@linaro.org> wrote: > Peter Maydell <peter.maydell@linaro.org> 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 @@ > > <li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li> > > <li><a href="qemu-ga-ref.html">Guest Agent Protocol > > Reference</a></li> > > <li><a href="interop/index.html">System Emulation > > Management and Interoperability Guide</a></li> > > + <li><a href="system/index.html">System Emulation User's > > Guide</a></li> > > <li><a href="specs/index.html">System Emulation Guest > > Hardware Specifications</a></li> > > </ul> > > </body> > > > 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
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 00000000000..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 00000000000..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 +
We want a user-facing manual which contains system emulation documentation. Create an empty one which we can populate. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- 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