Re: [PATCH v3 1/2] docs: remove non-reference uses of single backticks

[Eduardo Habkost]

On Thu, Sep 23, 2021 at 03:13:22PM -0400, 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>
> ---
>  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

Gosh, I think I'll never understand the syntax for links in
reStructuredText.

> +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:
[...]


Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>

-- 
Eduardo