riscv/qemu - qemu - Gitea: Git with a cup of tea

Commit Graph

Author	SHA1	Message	Date
Daniel P. Berrangé	704a256da8	docs: add "page source" link to sphinx documentation 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: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20201102130926.161183-5-berrange@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>	6 years ago
Yonggang Luo	a94a689cc5	docs: Fix Sphinx configuration for msys2/mingw 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: Paolo Bonzini <pbonzini@redhat.com>	6 years ago
Thomas Huth	1b11f28d05	configure: Bump the minimum required Python version to 3.6 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: Thomas Huth <thuth@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20200923162908.95372-1-thuth@redhat.com> Message-Id: <20200925154027.12672-16-alex.bennee@linaro.org>	6 years ago
Peter Maydell	4078ee5469	docs/sphinx: Add new qapi-doc Sphinx extension 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: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-8-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Comment and doc string formatting tweaked, unused method dropped, a few line breaks tweaked to follow PEP 8 more closely, MAINTAINERS section QAPI updated] Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 years ago
Paolo Bonzini	bac35bf517	docs: automatically track manual dependencies Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	6 years ago
Peter Maydell	bf3f857342	docs: Require Sphinx 1.6 or better 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>	6 years ago
Peter Maydell	e22684e34d	docs/conf.py: Raise ConfigError for bad Sphinx Python version 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: `be608ca231` 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: John Snow <jsnow@redhat.com> Message-id: 20200313163616.30674-1-peter.maydell@linaro.org	6 years ago
Peter Maydell	9b26a61093	Update copyright date for user-facing copyright strings 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-id: 20200316112006.19107-1-peter.maydell@linaro.org	6 years ago
Peter Maydell	de1572ca49	docs: Create defs.rst.inc as a place to define substitutions 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200228153619.9906-15-peter.maydell@linaro.org	7 years ago
Peter Maydell	758b617af8	configure: Check that sphinx-build is using Python 3 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com> Message-Id: <20200213175647.17628-3-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com>	7 years ago
Peter Maydell	6803d6e9a7	docs/sphinx: Add new hxtool Sphinx extension 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-4-peter.maydell@linaro.org	7 years ago
Peter Maydell	22b5ea75e1	docs/conf.py: Enable use of kerneldoc sphinx extension Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20190521122519.12573-4-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	7 years ago
Peter Maydell	27a296fce9	qemu-ga: Convert invocation documentation to rST 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> Message-id: 20190905131040.8350-1-peter.maydell@linaro.org	7 years ago
John Snow	cd231e13bd	sphinx: add qmp_lexer 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: Eduardo Habkost <ehabkost@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reported-by: Aarushi Mehta <mehta.aaru20@gmail.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20190603214653.29369-3-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>	7 years ago
Peter Maydell	6038f5fca5	docs/conf.py: Don't hard-code QEMU version 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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20190305172139.32662-12-peter.maydell@linaro.org Message-id: 20190228145624.24885-12-peter.maydell@linaro.org	8 years ago
Peter Maydell	f8cf7147f1	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	8 years ago
Peter Maydell	e250e867dc	docs/conf.py: Disable option warnings 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 <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20190305172139.32662-8-peter.maydell@linaro.org Message-id: 20190228145624.24885-8-peter.maydell@linaro.org	8 years ago
Peter Maydell	479fb8a511	docs/conf.py: Don't include rST sources in HTML build 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 <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20190305172139.32662-7-peter.maydell@linaro.org Message-id: 20190228145624.24885-7-peter.maydell@linaro.org	8 years ago
Peter Maydell	4fad3864a8	docs/conf.py: Configure the 'alabaster' theme 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 <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Message-id: 20190305172139.32662-6-peter.maydell@linaro.org Message-id: 20190228145624.24885-6-peter.maydell@linaro.org	8 years ago
Peter Maydell	07fd6563ae	docs/conf.py: Disable unused _static directory 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 <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20190305172139.32662-5-peter.maydell@linaro.org Message-id: 20190228145624.24885-5-peter.maydell@linaro.org	8 years ago
Peter Maydell	5329da6a4f	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	8 years ago

21 Commits (704a256da83d6535fce879ba4137299bbe626e5e)