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 <js...@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 <ehabk...@redhat.com> # if unrelated line wrapping changes are dropped -- Eduardo