From: Alexander Bulekov <alxndr@bu.edu>
To: John Snow <jsnow@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Thomas Huth" <thuth@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
qemu-devel@nongnu.org, "Eric Blake" <eblake@redhat.com>,
"Qiuhao Li" <Qiuhao.Li@outlook.com>,
"Darren Kenny" <darren.kenny@oracle.com>,
"Bandan Das" <bsd@redhat.com>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
"Paolo Bonzini" <pbonzini@redhat.com>,
"Alexandre Iooss" <erdnaxe@crans.org>,
"Mahmoud Mandour" <ma.mandourr@gmail.com>,
"Alex Bennée" <alex.bennee@linaro.org>
Subject: Re: [PATCH v3 1/2] docs: remove non-reference uses of single backticks
Date: Thu, 23 Sep 2021 16:54:13 -0400 [thread overview]
Message-ID: <20210923205413.lqlmrqkollrzbhbp@mozz.bu.edu> (raw)
In-Reply-To: <20210923191323.59726-2-jsnow@redhat.com>
On 210923 1513, John Snow wrote:
> The single backtick markup in ReST is the "default role". Currently,
> Sphinx's default role is called "content". Sphinx suggests you can use
> the "Any" role instead to turn any single-backtick enclosed item into a
> cross-reference.
>
> This is useful for things like autodoc for Python docstrings, where it's
> often nicer to reference other types with `foo` instead of the more
> laborious :py:meth:`foo`. It's also useful in multi-domain cases to
> easily reference definitions from other Sphinx domains, such as
> referencing C code definitions from outside of kerneldoc comments.
>
> Before we do that, though, we'll need to turn all existing usages of the
> "content" role to inline verbatim markup wherever it does not correctly
> resolve into a cross-refernece by using double backticks instead.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Alexander Bulekov <alxndr@bu.edu>
Thanks!
> ---
> docs/devel/fuzzing.rst | 9 +++++----
> docs/devel/tcg-plugins.rst | 2 +-
> docs/interop/live-block-operations.rst | 2 +-
> docs/system/guest-loader.rst | 2 +-
> qapi/block-core.json | 4 ++--
> include/qemu/module.h | 6 +++---
> qemu-options.hx | 4 ++--
> 7 files changed, 15 insertions(+), 14 deletions(-)
>
> diff --git a/docs/devel/fuzzing.rst b/docs/devel/fuzzing.rst
> index 2749bb9bed3..784ecb99e66 100644
> --- a/docs/devel/fuzzing.rst
> +++ b/docs/devel/fuzzing.rst
> @@ -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
> diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
> index dac5101a3c9..8bffff187f8 100644
> --- a/docs/devel/tcg-plugins.rst
> +++ b/docs/devel/tcg-plugins.rst
> @@ -212,7 +212,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::
>
> diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst
> index 9e3635b2338..814c29bbe1d 100644
> --- a/docs/interop/live-block-operations.rst
> +++ b/docs/interop/live-block-operations.rst
> @@ -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
> diff --git a/docs/system/guest-loader.rst b/docs/system/guest-loader.rst
> index 4320d1183f7..9ef9776bf07 100644
> --- a/docs/system/guest-loader.rst
> +++ b/docs/system/guest-loader.rst
> @@ -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.
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index c8ce1d9d5d8..0c64470edb2 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -446,11 +446,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)
> diff --git a/include/qemu/module.h b/include/qemu/module.h
> index 3deac0078b9..5fcc323b2a7 100644
> --- a/include/qemu/module.h
> +++ b/include/qemu/module.h
> @@ -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
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 8f603cc7e65..757ac6f2037 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1881,8 +1881,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.
> --
> 2.31.1
>
next prev parent reply other threads:[~2021-09-23 20:56 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-23 19:13 [PATCH v3 0/2] docs/sphinx: change default `role` to "any" John Snow
2021-09-23 19:13 ` [PATCH v3 1/2] docs: remove non-reference uses of single backticks John Snow
2021-09-23 20:37 ` Eduardo Habkost
2021-09-23 20:54 ` Alexander Bulekov [this message]
2021-09-23 19:13 ` [PATCH v3 2/2] docs/sphinx: change default role to "any" John Snow
2021-09-23 20:38 ` Eduardo Habkost
2021-09-24 9:25 ` Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210923205413.lqlmrqkollrzbhbp@mozz.bu.edu \
--to=alxndr@bu.edu \
--cc=Qiuhao.Li@outlook.com \
--cc=alex.bennee@linaro.org \
--cc=armbru@redhat.com \
--cc=bsd@redhat.com \
--cc=darren.kenny@oracle.com \
--cc=eblake@redhat.com \
--cc=ehabkost@redhat.com \
--cc=erdnaxe@crans.org \
--cc=jsnow@redhat.com \
--cc=ma.mandourr@gmail.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@redhat.com \
--cc=thuth@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).