aboutsummaryrefslogtreecommitdiff
path: root/docs/conf.py
AgeCommit message (Collapse)AuthorFilesLines
2020-10-17docs: Fix Sphinx configuration for msys2/mingwYonggang Luo1-1/+1
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 Huth1-2/+2
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 Maydell1-1/+5
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 Bonzini1-1/+1
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-14docs: Require Sphinx 1.6 or betterPeter Maydell1-2/+4
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 Maydell1-4/+5
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 Maydell1-1/+1
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 Maydell1-0/+6
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 Maydell1-0/+10
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 Maydell1-1/+2
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 Maydell1-1/+6
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 Maydell1-8/+10
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 Snow1-2/+2
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 Maydell1-5/+16
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 Maydell1-6/+31
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 Maydell1-0/+3
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 Maydell1-0/+3
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 Maydell1-2/+4
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 Maydell1-1/+5
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 Maydell1-0/+168
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
generated by cgit v1.1 at 2024-10-02 02:31:12 +0000