docs: standardize book titles to === with overline

Documents within a Sphinx manual are separate files and therefore can use
different conventions for headings. However, keeping some consistency is

docs: standardize book titles to === with overline

Documents within a Sphinx manual are separate files and therefore can use
different conventions for headings. However, keeping some consistency is
useful so that included files are easy to get right.

This patch uses a standard heading format for book titles, so that it is
obvious when a file sits at the top level toctree of a book or man page.
The heading is irrelevant for man pages, but keep it consistent as well.

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

docs: Move deprecation, build and license info out of system/

Now that we have a single Sphinx manual rather than multiple manuals,
we can provide a better place for "common to all of QEMU" informat

docs: Move deprecation, build and license info out of system/

Now that we have a single Sphinx manual rather than multiple manuals,
we can provide a better place for "common to all of QEMU" information
like the deprecation notices, build platforms, license information,
which we currently have in the system/ manual even though it applies
to all of QEMU.

Create a new directory about/ on the same level as system/, user/,
etc, and move these documents there.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-id: 20210705095547.15790-5-peter.maydell@linaro.org

show more ...

docs/index.rst, docs/index.html.in: Reorder manuals

Now that qemu-doc.html is no longer present, the ordering of manuals
within the top-level index page looks a bit odd. Reshuffle so that
the manual

docs/index.rst, docs/index.html.in: Reorder manuals

Now that qemu-doc.html is no longer present, the ordering of manuals
within the top-level index page looks a bit odd. Reshuffle so that
the manuals the user is most likely to be interested in are at the
top of the list, and the reference material is at the bottom.

Similarly, we reorder the index.rst file used as the base of
the "all manuals in one" documentation for readthedocs.

The new order is:
* system
* user
* tools
* interop
* specs
* QMP reference (if present)
* Guest agent protocol reference (if present)
* devel (if present)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200306171749.10756-7-peter.maydell@linaro.org

show more ...

qemu-doc: convert user-mode emulation to a separate Sphinx manual

The final addition to the set of QEMU manuals is the user-mode emulation
manual, which right now is included in qemu-doc.texi. Extr

qemu-doc: convert user-mode emulation to a separate Sphinx manual

The final addition to the set of QEMU manuals is the user-mode emulation
manual, which right now is included in qemu-doc.texi. Extract it and
convert it to rST, so that qemu-doc.texi covers only full system emulation.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200228153619.9906-2-peter.maydell@linaro.org
Message-id: 20200226113034.6741-2-pbonzini@redhat.com
[PMM: Fix makefile conflicts; add user manual to
index.rst and index.html.in; don't specify empty man_pages
list; fixed a few comments to say 'user' rather than 'system']
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

docs: Create new 'tools' manual

Some of the documentation for QEMU "tools" which are standalone
binaries like qemu-img is an awkward fit in our current 5-manual
split. We've put it into "interop", b

docs: Create new 'tools' manual

Some of the documentation for QEMU "tools" which are standalone
binaries like qemu-img is an awkward fit in our current 5-manual
split. We've put it into "interop", but they're not really
about interoperability.

Create a new top level manual "tools" which will be a better
home for this documentation. This commit creates an empty
initial manual; we will move the relevant documentation
files in a subsequent commit.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Acked-by: Paolo Bonzini <pbonzini@redhat.com>
Message-id: 20200217155415.30949-2-peter.maydell@linaro.org

show more ...

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 <peter.maydell@li

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-id: 20200116141511.16849-3-peter.maydell@linaro.org

show more ...

docs: provide documentation on the POWER9 XIVE interrupt controller

This documents the overall XIVE architecture and the XIVE support for
sPAPR guest machines (pseries).

It also provides documentat

docs: provide documentation on the POWER9 XIVE interrupt controller

This documents the overall XIVE architecture and the XIVE support for
sPAPR guest machines (pseries).

It also provides documentation on the 'info pic' command.

Signed-off-by: Cédric Le Goater <clg@kaod.org>
Message-Id: <20190521082411.24719-1-clg@kaod.org>
Reviewed-by: Satheesh Rajendran <sathnaga@linux.vnet.ibm.com>
Reviewed-by: Greg Kurz <groug@kaod.org>
Signed-off-by: David Gibson <david@gibson.dropbear.id.au>

show more ...

docs: Provide separate conf.py for each manual we want

By default Sphinx wants to build a single manual at once.
For QEMU, this doesn't suit us, because we want to have
separate manuals for "Develop

docs: Provide separate conf.py for each manual we want

By default Sphinx wants to build a single manual at once.
For QEMU, this doesn't suit us, because we want to have
separate manuals for "Developer's Guide", "User Manual",
and so on, and we don't want to ship the Developer's Guide
to end-users. However, we don't want to completely duplicate
conf.py for each manual, and we'd like to continue to
support "build all docs in one run" for third-party sites
like readthedocs.org.

Make the top-level conf.py support two usage forms:
(1) as a common config file which is included by the conf.py
for each of QEMU's manuals: in this case sphinx-build is run
multiple times, once per subdirectory.
(2) as a top level conf file which will result in building all
the manuals into a single document: in this case sphinx-build is
run once, on the top-level docs directory.

Provide per-manual conf.py files and top level pages for
our first two manuals:
* QEMU Developer's Guide (docs/devel)
* QEMU System Emulation Management and Interoperability Guide
(docs/interop)

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190305172139.32662-9-peter.maydell@linaro.org
Message-id: 20190228145624.24885-9-peter.maydell@linaro.org

show more ...

docs: Commit initial files from sphinx-quickstart

Commit the initial Sphinx conf.py and skeleton index.rst as
generated with sphinx-quickstart. We'll update these to
add QEMU-specific tweaks in subs

docs: Commit initial files from sphinx-quickstart

Commit the initial Sphinx conf.py and skeleton index.rst as
generated with sphinx-quickstart. We'll update these to
add QEMU-specific tweaks in subsequent commits.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Acked-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20190305172139.32662-4-peter.maydell@linaro.org
Message-id: 20190228145624.24885-4-peter.maydell@linaro.org

show more ...