aboutsummaryrefslogtreecommitdiff
path: root/docs/conf.py
AgeCommit message (Collapse)Author
2020-11-10docs: add "page source" link to sphinx documentationDaniel P. Berrangé
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>
2020-10-17docs: Fix Sphinx configuration for msys2/mingwYonggang Luo
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>
2020-10-02configure: Bump the minimum required Python version to 3.6Thomas Huth
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>
2020-09-29docs/sphinx: Add new qapi-doc Sphinx extensionPeter Maydell
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>
2020-08-21docs: automatically track manual dependenciesPaolo Bonzini
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-14docs: Require Sphinx 1.6 or betterPeter Maydell
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>
2020-03-30docs/conf.py: Raise ConfigError for bad Sphinx Python versionPeter Maydell
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: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: John Snow <jsnow@redhat.com> Message-id: 20200313163616.30674-1-peter.maydell@linaro.org
2020-03-22Update copyright date for user-facing copyright stringsPeter Maydell
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
2020-03-06docs: Create defs.rst.inc as a place to define substitutionsPeter Maydell
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
2020-02-15configure: Check that sphinx-build is using Python 3Peter Maydell
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>
2020-02-03docs/sphinx: Add new hxtool Sphinx extensionPeter Maydell
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
2019-12-17docs/conf.py: Enable use of kerneldoc sphinx extensionPeter Maydell
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>
2019-09-13qemu-ga: Convert invocation documentation to rSTPeter Maydell
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
2019-07-10sphinx: add qmp_lexerJohn Snow
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>
2019-03-07docs/conf.py: Don't hard-code QEMU versionPeter Maydell
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
2019-03-07docs: Provide separate conf.py for each manual we wantPeter Maydell
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
2019-03-07docs/conf.py: Disable option warningsPeter Maydell
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
2019-03-07docs/conf.py: Don't include rST sources in HTML buildPeter Maydell
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
2019-03-07docs/conf.py: Configure the 'alabaster' themePeter Maydell
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
2019-03-07docs/conf.py: Disable unused _static directoryPeter Maydell
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
2019-03-07docs: Commit initial files from sphinx-quickstartPeter Maydell
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