Commit Graph

16 Commits

Author SHA1 Message Date
Marc-André Lureau 73e6aec652 sphinx: adopt kernel readthedoc theme
The default "alabaster" sphinx theme has a couple shortcomings:
- the navbar moves along the page
- the search bar is not always at the same place
- it lacks some contrast and colours

The "rtd" theme from readthedocs.org is a popular third party theme used
notably by the kernel, with a custom style sheet. I like it better,
perhaps others do too. It also simplifies the "Edit on Gitlab" links.

Tweak a bit the custom theme to match qemu.org style, use the
QEMU logo, and favicon etc.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Tested-by: Bin Meng <bmeng.cn@gmail.com>
Message-Id: <20210323115328.4146052-1-marcandre.lureau@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
2021-05-14 15:05:03 +04:00
Stefan Reiter e0f7fc588d docs: don't install corresponding man page if guest agent is disabled
No sense outputting the qemu-ga and qemu-ga-ref man pages when the guest
agent binary itself is disabled. This mirrors behaviour from before the
meson switch.

Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
Message-Id: <20210128145801.14384-1-s.reiter@proxmox.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-02-08 14:43:55 +01:00
Peter Maydell b93f4fbdc4 docs: Build and install all the docs in a single manual
When we first converted our documentation to Sphinx, we split it into
multiple manuals (system, interop, tools, etc), which are all built
separately.  The primary driver for this was wanting to be able to
avoid shipping the 'devel' manual to end-users.  However, this is
working against the grain of the way Sphinx wants to be used and
causes some annoyances:
 * Cross-references between documents become much harder or
   possibly impossible
 * There is no single index to the whole documentation
 * Within one manual there's no links or table-of-contents info
   that lets you easily navigate to the others
 * The devel manual doesn't get published on the QEMU website
   (it would be nice to able to refer to it there)

Merely hiding our developer documentation from end users seems like
it's not enough benefit for these costs.  Combine all the
documentation into a single manual (the same way that the readthedocs
site builds it) and install the whole thing.  The previous manual
divisions remain as the new top level sections in the manual.

 * The per-manual conf.py files are no longer needed
 * The man_pages[] specifications previously in each per-manual
   conf.py move to the top level conf.py
 * docs/meson.build logic is simplified as we now only need to run
   Sphinx once for the HTML and then once for the manpages5B
 * The old index.html.in that produced the top-level page with
   links to each manual is no longer needed

Unfortunately this means that we now have to build the HTML
documentation into docs/manual in the build tree rather than directly
into docs/; otherwise it is too awkward to ensure we install only the
built manual and not also the dependency info, stamp file, etc.  The
manual still ends up in the same place in the final installed
directory, but anybody who was consulting documentation from within
the build tree will have to adjust where they're looking.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-id: 20210115154449.4801-1-peter.maydell@linaro.org
2021-01-19 15:45:14 +00:00
Peter Maydell fa56cf7e86 docs: Add qemu-storage-daemon(1) manpage to meson.build
In commit 1982e1602d we added a new qemu-storage-daemon(1) manpage.
At the moment new manpages have to be listed both in the conf.py for
Sphinx and also in docs/meson.build for Meson. We forgot the second
of those -- correct the omission.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20210108161416.21129-2-peter.maydell@linaro.org
2021-01-12 10:26:57 +00:00
Stefan Hajnoczi 23c02ace35 docs: generate qemu-storage-daemon-qmp-ref(7) man page
Although individual qemu-storage-daemon QMP commands are identical to
QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's
QMP commands. Generate a manual page of just the commands supported by
qemu-storage-daemon so that users know exactly what is available in
qemu-storage-daemon.

Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
block-core.json is at the h2 heading level.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20201209103802.350848-2-stefanha@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2020-12-18 11:48:39 +01:00
Marc-André Lureau daf07a6714 docs: set CONFDIR when running sphinx
The default configuration path /etc/qemu can be overriden with configure
options, and the generated documentation used to reflect it.

Fixes regression introduced in commit
f8aa24ea9a ("meson: sphinx-build").

Fixes: https://bugzilla.redhat.com/show_bug.cgi?id=1902537
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20201201183704.299697-1-marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-12-15 12:52:06 -05:00
Peter Maydell 773ee3f1ea docs: Split qemu-pr-helper documentation into tools manual
Split the documentation of the qemu-pr-helper binary into the tools
manual, and give it a manpage like our other standalone executables.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
2020-11-23 11:10:04 +00:00
Paolo Bonzini af2c0e854b meson: fix warning for bad sphinx-build
The warning was printing an empty string if the bad sphinx-build
was not passed on the command line.  Instead, always use the
path that was returned by find_program.

Reported-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-11-03 09:42:54 -05:00
Yonggang Luo e366766046 meson: Move the detection logic for sphinx to meson
Signed-off-by: Yonggang Luo <luoyonggang@gmail.com>
Message-Id: <20201015220626.418-4-luoyonggang@gmail.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-17 10:45:53 -04:00
Peter Maydell b3f4830ab3 meson.build: Make manuals depend on source to Sphinx extensions
The automatic dependency handling for Sphinx manuals only makes the output
depend on the input documentation files. This means that if you edit
the Python source of an extension then the documentation won't be
rebuilt.

Create a list of all the source files for the extensions and add
it to the dependencies for the manuals. This is similar to how we
handle the qapi_gen_depends list.

Because we don't try to identify which manuals are using which
Sphinx extensions, a change to the source of one extension will
always rebuild the entire manual set, not merely the manuals
which have changed. This is acceptable because we don't change
the extensions all that often.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-15-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Re rebuilding the enitre manual set being acceptable "because we
don't change the extensions all that often": we also rebuild it when
the QAPI generator code the qapidoc extension depends on changes.
This will inconvenience QAPI developers.  Can't be helped now.]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Peter Maydell eb937365fa meson.build: Move SPHINX_ARGS to top level meson.build file
We're going to want to use SPHINX_ARGS in both docs/meson.build
and tests/qapi-schema/meson.build. Move the definition up to the
top level file so it is available to both subdirectories.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-14-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Peter Maydell 4ac2ee194b docs/interop: Convert qemu-qmp-ref to rST
Convert qemu-qmp-ref to rST format. This includes dropping
the plain-text, pdf and info format outputs for this document;
as with all our other Sphinx-based documentation, we provide
HTML and manpage only.

The qemu-qmp-ref.rst is somewhat more stripped down than
the .texi was, because we do not (currently) attempt to
generate indexes for the commands, events and data types
being documented.

Again, we drop the direct link from index.html.in now that
the QMP ref is part of the interop manual.

This commit removes the code from the root meson.build file that
handled the various Texinfo-based outputs, because we no longer
generate any documentation except for the Sphinx HTML manuals and the
manpages, and the code can't handle having an empty list of files
to process.. We'll do further cleanup of the remainders of
Texinfo support in subsequent commits.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Unicode legacy literal dumbed down to plain string literal, TODO
comment on displaying QEMU version added, "make html" fixed,
storage-daemon/qapi/meson.build updated]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Peter Maydell db16115f87 docs/interop: Convert qemu-ga-ref to rST
Convert qemu-ga-ref to rST format. This includes dropping
the plain-text, pdf and info format outputs for this document;
as with all our other Sphinx-based documentation, we provide
HTML and manpage only.

The qemu-ga-ref.rst is somewhat more stripped down than
the .texi was, because we do not (currently) attempt to
generate indexes for the commands, events and data types
being documented.

As the GA ref is now part of the Sphinx 'interop' manual,
we can delete the direct link from index.html.in.

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-9-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Unicode legacy literal dumbed down to plain string literal, TODO
comment on displaying QEMU version added]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Marc-André Lureau 491e74c158 meson: pass docdir option
When cross-compiling, by default qemu_docdir is 'c:\Program Files\QEMU\'
which is not recognized as being an absolute path, and meson will end up
adding the prefix again.

Add an option to pass docdir location to meson, pre-prefixed like we do
with other directories, build qemu_docdir with the common suffix and use
that instead of config_host['qemu_docdir'].

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20200826110419.528931-7-marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-01 08:51:33 -04:00
Paolo Bonzini bac35bf517 docs: automatically track manual dependencies
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:41 -04:00
Paolo Bonzini f8aa24ea9a meson: sphinx-build
For now, sphinx is run on every invocation of make.  The previous mechanism
using $(wildcard) is not reproducible in Meson and was also brittle; for
example some .rst.inc files were left out.  The next patch will introduce
a Sphinx extension to emit a depfile.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:41 -04:00