On Thu, Sep 23, 2021 at 02:22:03PM -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>
Clear demonstration of the usefulness of patch 2/2 (these
occurrences of `foo` wouldn't have been added if the default role
was "any" because "any" errors out on invalid references).
However, it looks like there are unrelated changes:
[...]
> diff --git a/docs/devel/migration.rst b/docs/devel/migration.rst
> index 24012534827..6b1230f2d7f 100644
> --- a/docs/devel/migration.rst
> +++ b/docs/devel/migration.rst
> @@ -403,8 +403,8 @@ version_id. And the function ``load_state_old()`` (if present) is able to
> load state from minimum_version_id_old to minimum_version_id. This
> function is deprecated and will be removed when no more users are left.
>
> -There are *_V* forms of many ``VMSTATE_`` macros to load fields for version dependent fields,
> -e.g.
> +There are *_V* forms of many ``VMSTATE_`` macros to load fields for
> +version dependent fields, e.g.
Unrelated? Line wrapping change only.
>
> .. code:: c
>
> @@ -819,9 +819,9 @@ Postcopy now works with hugetlbfs backed memory:
> Postcopy with shared memory
> ---------------------------
>
> -Postcopy migration with shared memory needs explicit support from the other
> -processes that share memory and from QEMU. There are restrictions on the type of
> -memory that userfault can support shared.
> +Postcopy migration with shared memory needs explicit support from the
> +other processes that share memory and from QEMU. There are restrictions
> +on the type of memory that userfault can support shared.
Unrelated? Line wrapping change only.
Reviewed-by: Eduardo Habkost <ehabkost@redhat.com> # if unrelated line wrapping changes are dropped
--
Eduardo
Apologies for that -- it's bad rebase confetti. Something got merged automatically and it resulted in weird junk. Sorry for the noise.
--js