Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Thu, Aug 05, 2021 at 12:36:11PM -0400, Eduardo Habkost wrote: > On Wed, Aug 04, 2021 at 08:26:10PM -0400, John Snow wrote: > > On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost wrote: > > > > > On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote: > > > > 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. > > > > > > I believe "any" would be a very sensible default role for all > > > documents, but I don't know how to set default-role globally. > > > I'll try to find out. > > > > Oh, I actually fixed that issue I referenced there back in May -- I keep a > > patchset up to date whenever I work on modernizing the QAPI python code > > that actually DOES switch our default role to "any" ... I updated it just > > today, in fact. I will send it to the list if there's an appetite for it > > now. > > If you already have a patch that makes it possible to change the > default role to "any" globally, I'd be glad to include it in v2 > of this series. John had submitted the patches at: https://lore.kernel.org/qemu-devel/20210805004837.1775306-1-js...@redhat.com/ (Thanks!) If John's patches are merged, the only change needed in this series is the removal of the "default-role" line in patch 01/10. Instead of submitting v2 for a one-line change, I'm hoping I can just get Reviewed-by lines for this version. (the reviews can be conditional on the removal of the "default-role" line in patch 01/10) -- Eduardo
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Wed, Aug 04, 2021 at 08:26:10PM -0400, John Snow wrote: > On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost wrote: > > > On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote: > > > 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. > > > > I believe "any" would be a very sensible default role for all > > documents, but I don't know how to set default-role globally. > > I'll try to find out. > > Oh, I actually fixed that issue I referenced there back in May -- I keep a > patchset up to date whenever I work on modernizing the QAPI python code > that actually DOES switch our default role to "any" ... I updated it just > today, in fact. I will send it to the list if there's an appetite for it > now. If you already have a patch that makes it possible to change the default role to "any" globally, I'd be glad to include it in v2 of this series. -- Eduardo
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost wrote: > On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote: > > On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost > wrote: > > > > > > On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote: > > > > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost > 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. > > I believe "any" would be a very sensible default role for all > documents, but I don't know how to set default-role globally. > I'll try to find out. > > -- > Eduardo > Oh, I actually fixed that issue I referenced there back in May -- I keep a patchset up to date whenever I work on modernizing the QAPI python code that actually DOES switch our default role to "any" ... I updated it just today, in fact. I will send it to the list if there's an appetite for it now. --js
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote: > On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost wrote: > > > > On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote: > > > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost 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. I believe "any" would be a very sensible default role for all documents, but I don't know how to set default-role globally. I'll try to find out. -- Eduardo
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost wrote: > > On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote: > > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost 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-af374c789...@redhat.com/ -- PMM
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote: > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost wrote: > > > > Replace leftover of GTK-Doc #name syntax with `name`, and use > > default-role:: any, so we can add references to other functions, > > types, and macros. > > > > There are 3 cases that required extra care: > > - #TypeInfo.class_init: kernel-doc doesn't generate c:member:: > > directives, so references to C struct members are not possible > > yet. This was replaced with `TypeInfo`.class_init. > > - #CPUClass.reset and #DeviceClass.realize: cpu.h and qdev docs are not > > rendered using Sphinx yet, so use ``code`` syntax for those. > > > > Signed-off-by: Eduardo Habkost > > --- > > docs/devel/qom.rst | 25 + > > 1 file changed, 13 insertions(+), 12 deletions(-) > > > > 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). -- Eduardo
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost wrote: > > Replace leftover of GTK-Doc #name syntax with `name`, and use > default-role:: any, so we can add references to other functions, > types, and macros. > > There are 3 cases that required extra care: > - #TypeInfo.class_init: kernel-doc doesn't generate c:member:: > directives, so references to C struct members are not possible > yet. This was replaced with `TypeInfo`.class_init. > - #CPUClass.reset and #DeviceClass.realize: cpu.h and qdev docs are not > rendered using Sphinx yet, so use ``code`` syntax for those. > > Signed-off-by: Eduardo Habkost > --- > docs/devel/qom.rst | 25 + > 1 file changed, 13 insertions(+), 12 deletions(-) > > 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". thanks -- PMM
