On Thu, Sep 23, 2021 at 2:33 PM Eduardo Habkost <ehabkost@redhat.com> wrote:

> 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