mirror of https://github.com/xemu-project/xemu.git
Some Sphinx improvements
PR for 2 series: https://patchew.org/QEMU/20211015105344.152591-1-marcandre.lureau@redhat.com/ https://patchew.org/QEMU/20211004215238.1523082-1-jsnow@redhat.com/ -----BEGIN PGP SIGNATURE----- iQJQBAABCAA6FiEEh6m9kz+HxgbSdvYt2ujhCXWWnOUFAmGI508cHG1hcmNhbmRy ZS5sdXJlYXVAcmVkaGF0LmNvbQAKCRDa6OEJdZac5axBD/4oyGvcEiuN6PfqR5Er dCO8K2rOpeBgdpP88N26sdnP8xUAXfkijxPNbqv0MfRTxXPnEMDu6vHF6zH/2q63 kL9Qhjz6LZuRM9q2HgnTnJUM2Xnmsvp9QQyHI2M6vF+YHl/KVliGD8ICdPRm4zCb iYXJTnsCN8Fohc+mX0XiKD42lRv1GMpbuqPCKhjKNSwDDDo+wg6ByycPKa9iLe5S F3Peo1Sr/UkmGQ1icfRheXk9fZvVtoFVG68TWZzB41A+QOai63QkgjlcT7ELtoe/ bzOf6xZfIcKs1jHOVDKDnA5YzkAZlHKg+7tZpXdND62bRt2p1lLeeYiRTQAGnd+e wzKcWkBcwdtnN8ow/BUVwkdGoyXspJHhChhxZMSaaDIsk0oTKhjH4xE+rNu2Nscb E0G5+DwgP5m1rReLqGtbpD3AkndbnLE/AglxhVABbHlfI8ieB1GWc+8AXqaXIjBs ed7wGL+pOsdKMU+2PIKjc/4uuOwdLjiGK6UGAEZLS1XN9N3Kz9+PlTDGHPMw9Fw3 wYLMXvfwMfS/myVI7oYF9QvQjX9yMxjES2JHHZ+IMqAwleLXlr2wk119fZ5Vce/M eqaXgGwQ6hWFJW6HDvAk7RGCzwuL4MASMvxwV85HyLPdHv2UH/LVpFYjzL/nECt0 6zZyOdhsM84jdG81SknrMXx/dg== =khZf -----END PGP SIGNATURE----- Merge remote-tracking branch 'remotes/marcandre.lureau/tags/sphinx-pull-request' into staging Some Sphinx improvements PR for 2 series: https://patchew.org/QEMU/20211015105344.152591-1-marcandre.lureau@redhat.com/ https://patchew.org/QEMU/20211004215238.1523082-1-jsnow@redhat.com/ # gpg: Signature made Mon 08 Nov 2021 10:01:03 AM CET # gpg: using RSA key 87A9BD933F87C606D276F62DDAE8E10975969CE5 # gpg: issuer "marcandre.lureau@redhat.com" # gpg: Good signature from "Marc-André Lureau <marcandre.lureau@redhat.com>" [full] # gpg: aka "Marc-André Lureau <marcandre.lureau@gmail.com>" [full] * remotes/marcandre.lureau/tags/sphinx-pull-request: docs/sphinx: change default role to "any" docs: (further) remove non-reference uses of single backticks docs: remove non-reference uses of single backticks docs/sphinx: add 's' keyboard binding to focus search docs/sphinx: set navigation_with_keys=True meson: drop sphinx_template_files meson: drop sphinx_extn_depends tests/qapi-schema/meson: add depfile to sphinx doc docs/sphinx: add templates files to generated depfile docs/sphinx: add static files to generated depfile docs/sphinx: add loaded modules to generated depfile Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson
commit
260f9210d2
12
docs/conf.py
12
docs/conf.py
|
|
@ -74,7 +74,7 @@ needs_sphinx = '1.6'
|
|||
extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
templates_path = [os.path.join(qemu_docdir, '_templates')]
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
|
|
@ -85,6 +85,11 @@ source_suffix = '.rst'
|
|||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# Interpret `single-backticks` to be a cross-reference to any kind of
|
||||
# referenceable object. Unresolvable or ambiguous references will emit a
|
||||
# warning at build time.
|
||||
default_role = 'any'
|
||||
|
||||
# General information about the project.
|
||||
project = u'QEMU'
|
||||
copyright = u'2021, The QEMU Project Developers'
|
||||
|
|
@ -166,6 +171,7 @@ html_theme = 'sphinx_rtd_theme'
|
|||
if LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"):
|
||||
html_theme_options = {
|
||||
"style_nav_header_background": "#802400",
|
||||
"navigation_with_keys": True,
|
||||
}
|
||||
|
||||
html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
|
||||
|
|
@ -181,6 +187,10 @@ html_css_files = [
|
|||
'theme_overrides.css',
|
||||
]
|
||||
|
||||
html_js_files = [
|
||||
'custom.js',
|
||||
]
|
||||
|
||||
html_context = {
|
||||
"display_gitlab": True,
|
||||
"gitlab_user": "qemu-project",
|
||||
|
|
|
|||
|
|
@ -47,14 +47,14 @@ command line options for which a same-named Meson option exists;
|
|||
dashes in the command line are replaced with underscores.
|
||||
|
||||
Many checks on the compilation environment are still found in configure
|
||||
rather than `meson.build`, but new checks should be added directly to
|
||||
`meson.build`.
|
||||
rather than ``meson.build``, but new checks should be added directly to
|
||||
``meson.build``.
|
||||
|
||||
Patches are also welcome to move existing checks from the configure
|
||||
phase to `meson.build`. When doing so, ensure that `meson.build` does
|
||||
not use anymore the keys that you have removed from `config-host.mak`.
|
||||
Typically these will be replaced in `meson.build` by boolean variables,
|
||||
``get_option('optname')`` invocations, or `dep.found()` expressions.
|
||||
phase to ``meson.build``. When doing so, ensure that ``meson.build`` does
|
||||
not use anymore the keys that you have removed from ``config-host.mak``.
|
||||
Typically these will be replaced in ``meson.build`` by boolean variables,
|
||||
``get_option('optname')`` invocations, or ``dep.found()`` expressions.
|
||||
In general, the remaining checks have little or no interdependencies,
|
||||
so they can be moved one by one.
|
||||
|
||||
|
|
@ -298,7 +298,7 @@ comprises the following tasks:
|
|||
|
||||
- Add code to perform the actual feature check.
|
||||
|
||||
- Add code to include the feature status in `config-host.h`
|
||||
- Add code to include the feature status in ``config-host.h``
|
||||
|
||||
- Add code to print out the feature status in the configure summary
|
||||
upon completion.
|
||||
|
|
@ -334,7 +334,7 @@ The other supporting code is generally simple::
|
|||
|
||||
For the configure script to parse the new option, the
|
||||
``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make
|
||||
update-buildoptions`` (or just `make`) will take care of updating it.
|
||||
update-buildoptions`` (or just ``make``) will take care of updating it.
|
||||
|
||||
|
||||
Support scripts
|
||||
|
|
|
|||
|
|
@ -182,10 +182,11 @@ The output should contain a complete list of matched MemoryRegions.
|
|||
|
||||
OSS-Fuzz
|
||||
--------
|
||||
QEMU is continuously fuzzed on `OSS-Fuzz` __(https://github.com/google/oss-fuzz).
|
||||
By default, the OSS-Fuzz build will try to fuzz every fuzz-target. Since the
|
||||
generic-fuzz target requires additional information provided in environment
|
||||
variables, we pre-define some generic-fuzz configs in
|
||||
QEMU is continuously fuzzed on `OSS-Fuzz
|
||||
<https://github.com/google/oss-fuzz>`_. By default, the OSS-Fuzz build
|
||||
will try to fuzz every fuzz-target. Since the generic-fuzz target
|
||||
requires additional information provided in environment variables, we
|
||||
pre-define some generic-fuzz configs in
|
||||
``tests/qtest/fuzz/generic_fuzz_configs.h``. Each config must specify:
|
||||
|
||||
- ``.name``: To identify the fuzzer config
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ The hotpages plugin can be configured using the following arguments:
|
|||
|
||||
This is an instruction classifier so can be used to count different
|
||||
types of instructions. It has a number of options to refine which get
|
||||
counted. You can give a value to the `count` argument for a class of
|
||||
counted. You can give a value to the ``count`` argument for a class of
|
||||
instructions to break it down fully, so for example to see all the system
|
||||
registers accesses::
|
||||
|
||||
|
|
|
|||
|
|
@ -640,7 +640,7 @@ at this point:
|
|||
(QEMU) block-job-complete device=job0
|
||||
|
||||
In either of the above cases, if you once again run the
|
||||
`query-block-jobs` command, there should not be any active block
|
||||
``query-block-jobs`` command, there should not be any active block
|
||||
operation.
|
||||
|
||||
Comparing 'commit' and 'mirror': In both then cases, the overlay images
|
||||
|
|
|
|||
|
|
@ -37,15 +37,6 @@ endif
|
|||
if build_docs
|
||||
SPHINX_ARGS += ['-Dversion=' + meson.project_version(), '-Drelease=' + config_host['PKGVERSION']]
|
||||
|
||||
sphinx_extn_depends = [ meson.current_source_dir() / 'sphinx/depfile.py',
|
||||
meson.current_source_dir() / 'sphinx/hxtool.py',
|
||||
meson.current_source_dir() / 'sphinx/kerneldoc.py',
|
||||
meson.current_source_dir() / 'sphinx/kernellog.py',
|
||||
meson.current_source_dir() / 'sphinx/qapidoc.py',
|
||||
meson.current_source_dir() / 'sphinx/qmp_lexer.py',
|
||||
qapi_gen_depends ]
|
||||
sphinx_template_files = [ meson.project_source_root() / 'docs/_templates/footer.html' ]
|
||||
|
||||
have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT')
|
||||
|
||||
man_pages = {
|
||||
|
|
@ -77,7 +68,6 @@ if build_docs
|
|||
output: 'docs.stamp',
|
||||
input: files('conf.py'),
|
||||
depfile: 'docs.d',
|
||||
depend_files: [ sphinx_extn_depends, sphinx_template_files ],
|
||||
command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
|
||||
'-Ddepfile_stamp=@OUTPUT0@',
|
||||
'-b', 'html', '-d', private_dir,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
document.addEventListener('keydown', (event) => {
|
||||
// find a better way to look it up?
|
||||
let search_input = document.getElementsByName('q')[0];
|
||||
|
||||
if (event.code === 'KeyS' && document.activeElement !== search_input) {
|
||||
event.preventDefault();
|
||||
search_input.focus();
|
||||
}
|
||||
});
|
||||
|
|
@ -12,6 +12,8 @@
|
|||
|
||||
import os
|
||||
import sphinx
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
__version__ = '1.0'
|
||||
|
||||
|
|
@ -20,8 +22,21 @@ def get_infiles(env):
|
|||
yield env.doc2path(x)
|
||||
yield from ((os.path.join(env.srcdir, dep)
|
||||
for dep in env.dependencies[x]))
|
||||
for mod in sys.modules.values():
|
||||
if hasattr(mod, '__file__'):
|
||||
if mod.__file__:
|
||||
yield mod.__file__
|
||||
# this is perhaps going to include unused files:
|
||||
for static_path in env.config.html_static_path + env.config.templates_path:
|
||||
for path in Path(static_path).rglob('*'):
|
||||
yield str(path)
|
||||
|
||||
def write_depfile(app, env):
|
||||
|
||||
def write_depfile(app, exception):
|
||||
if exception:
|
||||
return
|
||||
|
||||
env = app.env
|
||||
if not env.config.depfile:
|
||||
return
|
||||
|
||||
|
|
@ -42,7 +57,7 @@ def write_depfile(app, env):
|
|||
def setup(app):
|
||||
app.add_config_value('depfile', None, 'env')
|
||||
app.add_config_value('depfile_stamp', None, 'env')
|
||||
app.connect('env-updated', write_depfile)
|
||||
app.connect('build-finished', write_depfile)
|
||||
|
||||
return dict(
|
||||
version = __version__,
|
||||
|
|
|
|||
|
|
@ -51,4 +51,4 @@ The full syntax of the guest-loader is::
|
|||
|
||||
``bootargs=<args>``
|
||||
This is an optional field for kernel blobs which will pass command
|
||||
like via the `/chosen/module@<addr>/bootargs` node.
|
||||
like via the ``/chosen/module@<addr>/bootargs`` node.
|
||||
|
|
|
|||
|
|
@ -77,9 +77,9 @@ CPUID
|
|||
|
||||
Due to its myriad dependencies, SGX is currently not listed as supported
|
||||
in any of Qemu's built-in CPU configuration. To expose SGX (and SGX Launch
|
||||
Control) to a guest, you must either use `-cpu host` to pass-through the
|
||||
Control) to a guest, you must either use ``-cpu host`` to pass-through the
|
||||
host CPU model, or explicitly enable SGX when using a built-in CPU model,
|
||||
e.g. via `-cpu <model>,+sgx` or `-cpu <model>,+sgx,+sgxlc`.
|
||||
e.g. via ``-cpu <model>,+sgx`` or ``-cpu <model>,+sgx,+sgxlc``.
|
||||
|
||||
All SGX sub-features enumerated through CPUID, e.g. SGX2, MISCSELECT,
|
||||
ATTRIBUTES, etc... can be restricted via CPUID flags. Be aware that enforcing
|
||||
|
|
@ -126,7 +126,7 @@ creating VM with SGX.
|
|||
Feature Control
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Qemu SGX updates the `etc/msr_feature_control` fw_cfg entry to set the SGX
|
||||
Qemu SGX updates the ``etc/msr_feature_control`` fw_cfg entry to set the SGX
|
||||
(bit 18) and SGX LC (bit 17) flags based on their respective CPUID support,
|
||||
i.e. existing guest firmware will automatically set SGX and SGX LC accordingly,
|
||||
assuming said firmware supports fw_cfg.msr_feature_control.
|
||||
|
|
|
|||
|
|
@ -77,14 +77,14 @@ void module_allow_arch(const char *arch);
|
|||
/**
|
||||
* DOC: module info annotation macros
|
||||
*
|
||||
* `scripts/modinfo-collect.py` will collect module info,
|
||||
* ``scripts/modinfo-collect.py`` will collect module info,
|
||||
* using the preprocessor and -DQEMU_MODINFO.
|
||||
*
|
||||
* `scripts/modinfo-generate.py` will create a module meta-data database
|
||||
* ``scripts/modinfo-generate.py`` will create a module meta-data database
|
||||
* from the collected information so qemu knows about module
|
||||
* dependencies and QOM objects implemented by modules.
|
||||
*
|
||||
* See `*.modinfo` and `modinfo.c` in the build directory to check the
|
||||
* See ``*.modinfo`` and ``modinfo.c`` in the build directory to check the
|
||||
* script results.
|
||||
*/
|
||||
#ifdef QEMU_MODINFO
|
||||
|
|
|
|||
|
|
@ -491,11 +491,11 @@
|
|||
# @granularity: granularity of the dirty bitmap in bytes (since 1.4)
|
||||
#
|
||||
# @recording: true if the bitmap is recording new writes from the guest.
|
||||
# Replaces `active` and `disabled` statuses. (since 4.0)
|
||||
# Replaces ``active`` and ``disabled`` statuses. (since 4.0)
|
||||
#
|
||||
# @busy: true if the bitmap is in-use by some operation (NBD or jobs)
|
||||
# and cannot be modified via QMP or used by another operation.
|
||||
# Replaces `locked` and `frozen` statuses. (since 4.0)
|
||||
# Replaces ``locked`` and ``frozen`` statuses. (since 4.0)
|
||||
#
|
||||
# @persistent: true if the bitmap was stored on disk, is scheduled to be stored
|
||||
# on disk, or both. (since 4.0)
|
||||
|
|
|
|||
|
|
@ -1895,8 +1895,8 @@ SRST
|
|||
Valid parameters are:
|
||||
|
||||
``grab-mod=<mods>`` : Used to select the modifier keys for toggling
|
||||
the mouse grabbing in conjunction with the "g" key. `<mods>` can be
|
||||
either `lshift-lctrl-lalt` or `rctrl`.
|
||||
the mouse grabbing in conjunction with the "g" key. ``<mods>`` can be
|
||||
either ``lshift-lctrl-lalt`` or ``rctrl``.
|
||||
|
||||
``alt_grab=on|off`` : Use Control+Alt+Shift-g to toggle mouse grabbing.
|
||||
This parameter is deprecated - use ``grab-mod`` instead.
|
||||
|
|
|
|||
|
|
@ -241,7 +241,7 @@ if build_docs
|
|||
output: ['doc-good.txt'],
|
||||
input: files('doc-good.json', 'doc-good.rst'),
|
||||
build_by_default: true,
|
||||
depend_files: sphinx_extn_depends,
|
||||
depfile: 'docs.d',
|
||||
# We use -E to suppress Sphinx's caching, because
|
||||
# we want it to always really run the QAPI doc
|
||||
# generation code. It also means we don't
|
||||
|
|
@ -250,6 +250,8 @@ if build_docs
|
|||
'-b', 'text', '-E',
|
||||
'-c', meson.project_source_root() / 'docs',
|
||||
'-D', 'master_doc=doc-good',
|
||||
'-Ddepfile=@DEPFILE@',
|
||||
'-Ddepfile_stamp=doc-good.stamp',
|
||||
meson.current_source_dir(),
|
||||
meson.current_build_dir()])
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue