[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax
From: |
Peter Maydell |
Subject: |
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` |
Date: |
Wed, 4 Aug 2021 21:42:24 +0100 |
On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote:
> > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost <ehabkost@redhat.com> wrote:
> > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > > index e5fe3597cd8..9c1be5d7fc2 100644
> > > --- a/docs/devel/qom.rst
> > > +++ b/docs/devel/qom.rst
> > > @@ -3,6 +3,7 @@ The QEMU Object Model (QOM)
> > > ===========================
> > >
> > > .. highlight:: c
> > > +.. default-role:: any
> > >
> > > The QEMU Object Model provides a framework for registering user creatable
> > > types and instantiating objects from those types. QOM provides the
> > > following
> > > @@ -42,8 +43,8 @@ features:
> > >
> > > type_init(my_device_register_types)
> > >
> > > -In the above example, we create a simple type that is described by
> > > #TypeInfo.
> > > -#TypeInfo describes information about the type including what it inherits
> > > +In the above example, we create a simple type that is described by
> > > `TypeInfo`.
> > > +`TypeInfo` describes information about the type including what it
> > > inherits
> >
> > I've just gone through all of docs/ finding the places where we had `foo`
> > and
> > probably meant ``foo``, so please don't add any new ones. I would suggest
> > that you either use the ``double-backtick`` syntax to render as fixed-width
> > font, or use an explicit role tag so readers of the rST source can tell that
> > that's what you meant to use, ie avoid "default-role".
>
> I don't understand why that would be a reason to not use
> default-role. With default-role, we get an error when misusing
> `foo`. Without default-role, misuse won't be detected at all
> (except by manual inspection).
Ah, I didn't realize that we got an error if we set the default-role
to 'any'. That certainly makes it nicer than the default default
of 'cite'.
Is there a sensible default-role we can use as the default for the whole manual,
rather than only declaring it in individual .rst files ? One of the
things I don't
like about the change here is that it means that `thing` in this individual .rst
file is different from `thing` in every other .rst file in our docs.
Ccing John, who I have just remembered wrote something about Sphinx roles
a few months back:
https://lore.kernel.org/qemu-devel/9fe98807-7d68-2c86-163a-af374c789401@redhat.com/
-- PMM