- Feb 16, 2023
-
-
Dr. David Alan Gilbert authored
Remove all the virtiofsd build and docs infrastructure. Signed-off-by:
Dr. David Alan Gilbert <dgilbert@redhat.com> Acked-by:
Stefan Hajnoczi <stefanha@redhat.com>
-
- Feb 02, 2023
-
-
Marc-André Lureau authored
It looks like this is no longer wanted, we only build the html output. Signed-off-by:
Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by:
Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20230110132700.833690-6-marcandre.lureau@redhat.com> Signed-off-by:
Alex Bennée <alex.bennee@linaro.org> Message-Id: <20230124180127.1881110-9-alex.bennee@linaro.org>
-
- Jun 27, 2022
-
-
Martin Liška authored
Fixes the following Sphinx warning (treated as error) starting with 5.0 release: Warning, treated as error: Invalid configuration value found: 'language = None'. Update your configuration to a valid langauge code. Falling back to 'en' (English). Signed-off-by:
Martin Liska <mliska@suse.cz> Message-id: e91e51ee-48ac-437e-6467-98b56ee40042@suse.cz Reviewed-by:
Peter Maydell <peter.maydell@linaro.org> Signed-off-by:
-
- Jan 28, 2022
-
-
Peter Maydell authored
It's a new year; update the copyright strings for our help/version/about information and for our documentation. Signed-off-by:
Philippe Mathieu-Daudé <f4bug@amsat.org> Message-id: 20220120124713.288303-1-peter.maydell@linaro.org
-
- Dec 21, 2021
-
-
Marc-André Lureau authored
Add a new dbus-doc directive to import D-Bus interfaces documentation from the introspection XML. The comments annotations follow the gtkdoc/kerneldoc style, and should be formatted with reST. Note: I realize after the fact that I was implementing those modules with sphinx 4, and that we have much lower requirements. Instead of lowering the features and code (removing type annotations etc), let's have a warning in the documentation when the D-Bus modules can't be used, and point to the source XML file in that case. Signed-off-by:
Gerd Hoffmann <kraxel@redhat.com>
-
- Nov 08, 2021
-
-
John Snow authored
This interprets single-backtick syntax in all of our Sphinx docs as a cross-reference to *something*, including Python symbols. From here on out, new uses of `backticks` will cause a build failure if the target cannot be referenced. Signed-off-by:
John Snow <jsnow@redhat.com> Reviewed-by:
Eduardo Habkost <ehabkost@redhat.com> Reviewed-by:
-
Marc-André Lureau authored
This is pretty ubiquitous. ('/' is already taken by some browsers for quick search) Signed-off-by:Paolo Bonzini <pbonzini@redhat.com>
-
Marc-André Lureau authored
Allow navigating to the previous/next page using the keyboard's left and right arrows. I wish this would be the default, and that the themes would provide more key navigation, but that doesn't seem on the roadmap. Signed-off-by:
-
Marc-André Lureau authored
Signed-off-by:
-
- Jul 18, 2021
-
-
Peter Maydell authored
In commit 6d8980a3 we updated the copyright string we present to the user in -version output, About dialogs, etc, but we forgot that the Sphinx manuals have a separate copyright string setting. Update that one too. Signed-off-by:
Markus Armbruster <armbru@redhat.com> Reviewed-by:
-
- Jun 03, 2021
-
-
Damien Goutte-Gattat authored
The 4.x branch of Sphinx introduces a breaking change, as generated man pages are now written to subdirectories corresponding to the manual section they belong to. This results in `make install` erroring out when attempting to install the man pages, because they are not where it expects to find them. This patch restores the behavior of Sphinx 3.x regarding man pages. Resolves: https://gitlab.com/qemu-project/qemu/-/issues/256 Signed-off-by:
Damien Goutte-Gattat <dgouttegattat@incenp.org> Message-id: 20210503161422.15028-1-dgouttegattat@incenp.org Reviewed-by:
-
- May 14, 2021
-
-
Marc-André Lureau authored
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:
Bin Meng <bmeng.cn@gmail.com> Message-Id: <20210323115328.4146052-1-marcandre.lureau@redhat.com> Reviewed-by:
-
- Jan 19, 2021
-
-
Peter Maydell authored
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:
-
- Nov 10, 2020
-
-
Daniel P. Berrangé authored
Add a link to the top of the sidebar in every docs page that takes the user back to the source code in gitlab. Signed-off-by:
Thomas Huth <thuth@redhat.com>
-
- Oct 17, 2020
-
-
Yonggang Luo authored
Python doesn't support running ../scripts/kernel-doc directly. Signed-off-by:
Yonggang Luo <luoyonggang@gmail.com> Message-Id: <20201015220626.418-2-luoyonggang@gmail.com> Signed-off-by:
-
- Oct 02, 2020
-
-
Thomas Huth authored
All our supported build platforms have Python 3.6 or newer nowadays, and there are some useful features in Python 3.6 which are not available in 3.5 yet (e.g. the type hint annotations which will allow us to statically type the QAPI parser), so let's bump the minimum Python version to 3.6 now. Signed-off-by:
-
- Sep 29, 2020
-
-
Peter Maydell authored
Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by:
-
- Aug 21, 2020
-
-
Paolo Bonzini authored
Signed-off-by:
-
- Apr 14, 2020
-
-
Peter Maydell authored
Versions of Sphinx older than 1.6 can't build all of our documentation, because they are too picky about the syntax of the argument to the option:: directive; see Sphinx bugs #646, #3366: https://github.com/sphinx-doc/sphinx/issues/646 https://github.com/sphinx-doc/sphinx/issues/3366 Trying to build with a 1.4.x Sphinx fails with docs/system/images.rst:4: SEVERE: Duplicate ID: "cmdoption-qcow2-arg-encrypt" and a 1.5.x Sphinx fails with docs/system/invocation.rst:544: WARNING: Malformed option description '[enable=]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args" Update our needs_sphinx setting to indicate that we require at least 1.6. This will allow configure to fall back to "don't build the docs" rather than causing the build to fail entirely, which is probably what most users building on a host old enough to have such an old Sphinx would want; if they do want the docs then they'll have a useful indication of what they need to do (upgrade Sphinx!) rather than a confusing error message. In theory our distro support policy would suggest that we should support building on the Sphinx shipped in those distros, but: * EPEL7 has Sphinx 1.2.3 (which we've never supported!) * Debian Stretch has Sphinx 1.4.8 Trying to get our docs to work with Sphinx 1.4 is not tractable for the 5.0 release and I'm not sure it's worthwhile effort anyway; at least with this change the build as a whole now succeeds. Thanks to John Snow for doing the investigation and testing to confirm what Sphinx versions fail in what ways and what distros shipped what. Signed-off-by:
Richard Henderson <richard.henderson@linaro.org>
-
- Mar 30, 2020
-
-
Peter Maydell authored
Raise ConfigError rather than VersionRequirementError when we detect that the Python being used by Sphinx is too old. Currently the way we flag the Python version problem up to the user causes Sphinx to print an unnecessary Python stack trace as well as the information about the problem; in most versions of Sphinx this is unavoidable. The upstream Sphinx developers kindly added a feature to allow conf.py to report errors to the user without the backtrace: https://github.com/sphinx-doc/sphinx/commit/be608ca2313fc08eb842f3dc19d0f5d2d8227d08 but the exception type they chose for this was ConfigError. Switch to ConfigError, which won't make any difference with currently deployed Sphinx versions, but will be prettier one day when the user is using a Sphinx version with the new feature. Signed-off-by:
-
- Mar 22, 2020
-
-
Peter Maydell authored
Update the copyright date to 2020 for the copyright strings which are user-facing and represent overall copyright info for all of QEMU. Reported-by:
John Arbuckle <programmingkidx@gmail.com> Signed-off-by:
Philippe Mathieu-Daudé <philmd@redhat.com> Message-id: 20200316112006.19107-1-peter.maydell@linaro.org
-
- Mar 06, 2020
-
-
Peter Maydell authored
Rather than accumulating generally useful rST substitution definitions in individual rST files, create a defs.rst.inc where we can define these. To start with it has the |qemu_system| definition from qemu-block-drivers.rst. Add a comment noting a pitfall where putting literal markup in the definition of |qemu_system| makes it misrender manpage output; this means the point-of-use must handle the literal markup (which is almost always done by having it inside a parsed-literal block). Signed-off-by:
Kashyap Chamarthy <kchamart@redhat.com> Tested-by:
-
- Feb 15, 2020
-
-
Peter Maydell authored
Currently configure's has_sphinx_build() check simply runs a dummy sphinx-build and either passes or fails. This means that "no sphinx-build at all" and "sphinx-build exists but is too old" are both reported the same way. Further, we want to assume that all the Python we write is running with at least Python 3.5; configure checks that for our scripts, but Sphinx extensions run with whatever Python version sphinx-build itself is using. Add a check to our conf.py which makes sphinx-build fail if it would be running our extensions with an old Python, and handle this in configure so we can report failure helpfully to the user. This will mean that configure --enable-docs will fail like this if the sphinx-build provided is not suitable: Warning: sphinx-build exists but it is either too old or uses too old a Python version ERROR: User requested feature docs configure was not able to find it. Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx (As usual, the default is to simply not build the docs, as we would if sphinx-build wasn't present at all.) Signed-off-by:Wainer dos Santos Moschetta <wainersm@redhat.com> Message-Id: <20200213175647.17628-3-peter.maydell@linaro.org> Signed-off-by:
-
- Feb 03, 2020
-
-
Peter Maydell authored
Some of our documentation includes sections which are created by assembling fragments of texinfo from a .hx source file into a .texi file, which is then included from qemu-doc.texi or qemu-img.texi. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which reads the .hx file and process it. So instead of: * makefile produces foo.texi from foo.hx * qemu-doc.texi says '@include foo.texi' we have: * qemu-doc.rst says 'hxtool-doc:: foo.hx' * the Sphinx extension for hxtool has code that runs to handle that Sphinx directive which reads the .hx file and emits the appropriate documentation contents This is pretty much the same way the kerneldoc extension works right now. It also has the advantage that it should work for third-party services like readthedocs that expect to build the docs directly with sphinx rather than by invoking our makefiles. In this commit we implement the hxtool extension. Note that syntax errors in the rST fragments will be correctly reported to the user with the filename and line number within the hx file. Signed-off-by:
-
- Dec 17, 2019
-
-
Peter Maydell authored
Signed-off-by:
-
- Sep 13, 2019
-
-
Peter Maydell authored
The qemu-ga documentation is currently in qemu-ga.texi in Texinfo format, which we present to the user as: * a qemu-ga manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-ga manpage * part of the interop/ Sphinx manual Signed-off-by:
Michael Roth <mdroth@linux.vnet.ibm.com> Tested-by:
-
- Jul 10, 2019
-
-
John Snow authored
Sphinx, through Pygments, does not like annotated json examples very much. In some versions of Sphinx (1.7), it will render the non-json portions of code blocks in red, but in newer versions (2.0) it will throw an exception and not highlight the block at all. Though we can suppress this warning, it doesn't bring back highlighting on non-strict json blocks. We can alleviate this by creating a custom lexer for QMP examples that allows us to properly highlight these examples in a robust way, keeping our directionality and elision notations. Signed-off-by:
Aarushi Mehta <mehta.aaru20@gmail.com> Reviewed-by:
-
- Mar 07, 2019
-
-
Peter Maydell authored
Don't hard-code the QEMU version number into conf.py. Instead we either pass it to sphinx-build on the command line, or (if doing a standalone Sphinx run in a readthedocs.org setup) extract it from the VERSION file. Signed-off-by:
Aleksandar Markovic <amarkovic@wavecomp.com> Reviewed-by:
-
Peter Maydell authored
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:
-
Peter Maydell authored
sphinx-build complains about using :option: to mark up option flags that it doesn't know about (because they were not defined using the "option::" directive): docs/pr-manager.rst:68: WARNING: unknown option: -d Suppress these warnings. This way we get the semantic markup of the option flag but no cross-referencing hyperlink. Signed-off-by:
-
Peter Maydell authored
Sphinx defaults to including all the rST source files in the HTML build and making each HTML page link to the source file. Disable that. Signed-off-by:
-
Peter Maydell authored
Add the 'navigation' bar to the sidebar, which for some reason is not enabled by default. Remove 'relations', which is effectively disabled anyway and isn't useful for us. This requires that we mandate having at least Sphinx 1.3, where the theme was added. Signed-off-by:
-
Peter Maydell authored
We don't yet have any custom static files, so disable this config file setting to avoid a warning from sphinx about not being able to find the directory. Signed-off-by:
-
Peter Maydell authored
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:
-
