[1/2] documentation/README: improve BitBake manual referencing guidelines

Submitted by Michael Opdenacker on July 27, 2021, 2:11 p.m. | Patch ID: 179966

Details

Message ID 20210727141200.128209-1-michael.opdenacker@bootlin.com
State New
Headers show

Commit Message

Michael Opdenacker July 27, 2021, 2:11 p.m.
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/README | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

Patch hide | download patch | download mbox

diff --git a/documentation/README b/documentation/README
index f9e803a28b..1d4d213076 100644
--- a/documentation/README
+++ b/documentation/README
@@ -328,11 +328,15 @@  The sphinx.ext.intersphinx extension is enabled by default
 so that we can cross reference content from other Sphinx based
 documentation projects, such as the BitBake manual.
 
-References to the bitbake manual can be done like this:
-
-  See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
-or
+References to the BitBake manual can be done:
+ - With a specific description instead of the section name:
+  :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
+ - With the section name:
+  ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
+ - With a BitBake variable name:
   :term:`bitbake:BB_NUMBER_PARSE_THREADS`
+ - Linking to the entire BitBake manual:
+  :doc:`BitBake User Manual <bitbake:index>`
 
 Submitting documentation changes
 ================================

Comments

Quentin Schulz July 27, 2021, 2:14 p.m.
Hi Michael,

On Tue, Jul 27, 2021 at 04:11:59PM +0200, Michael Opdenacker wrote:
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  documentation/README | 12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/documentation/README b/documentation/README
> index f9e803a28b..1d4d213076 100644
> --- a/documentation/README
> +++ b/documentation/README
> @@ -328,11 +328,15 @@ The sphinx.ext.intersphinx extension is enabled by default
>  so that we can cross reference content from other Sphinx based
>  documentation projects, such as the BitBake manual.
>  
> -References to the bitbake manual can be done like this:
> -
> -  See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
> -or
> +References to the BitBake manual can be done:
> + - With a specific description instead of the section name:
> +  :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
> + - With the section name:
> +  ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
> + - With a BitBake variable name:
>    :term:`bitbake:BB_NUMBER_PARSE_THREADS`

I'd rather not specify bitbake: for terms so that they can be overriden
from within yocto-docs if need be, without needing to modify all the
refs spread over the whole git repo.

Cheers,
Quentin
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1561): https://lists.yoctoproject.org/g/docs/message/1561
Mute This Topic: https://lists.yoctoproject.org/mt/84482573/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Michael Opdenacker July 27, 2021, 2:29 p.m.
Hi Quentin,

On 7/27/21 4:14 PM, Quentin Schulz wrote:
> Hi Michael,
>
> On Tue, Jul 27, 2021 at 04:11:59PM +0200, Michael Opdenacker wrote:
>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>> ---
>>  documentation/README | 12 ++++++++----
>>  1 file changed, 8 insertions(+), 4 deletions(-)
>>
>> diff --git a/documentation/README b/documentation/README
>> index f9e803a28b..1d4d213076 100644
>> --- a/documentation/README
>> +++ b/documentation/README
>> @@ -328,11 +328,15 @@ The sphinx.ext.intersphinx extension is enabled by default
>>  so that we can cross reference content from other Sphinx based
>>  documentation projects, such as the BitBake manual.
>>  
>> -References to the bitbake manual can be done like this:
>> -
>> -  See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
>> -or
>> +References to the BitBake manual can be done:
>> + - With a specific description instead of the section name:
>> +  :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
>> + - With the section name:
>> +  ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax` option
>> + - With a BitBake variable name:
>>    :term:`bitbake:BB_NUMBER_PARSE_THREADS`
> I'd rather not specify bitbake: for terms so that they can be overriden
> from within yocto-docs if need be, without needing to modify all the
> refs spread over the whole git repo.


Thanks for the feedback. However, I'm not sure what you mean here... Do
you mean we should replace all instances of ":term:`bitbake:VARIABLE`"
by ":term:`VARIABLE`"?

If I understand well, if VARIABLE is only defined in the BitBake manual,
we will directly get a reference in that manual.

Cheers,
Michael.
Nicolas Dechesne July 27, 2021, 3 p.m.
On Tue, Jul 27, 2021 at 4:29 PM Michael Opdenacker <
michael.opdenacker@bootlin.com> wrote:

> Hi Quentin,
>
> On 7/27/21 4:14 PM, Quentin Schulz wrote:
> > Hi Michael,
> >
> > On Tue, Jul 27, 2021 at 04:11:59PM +0200, Michael Opdenacker wrote:
> >> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> >> ---
> >>  documentation/README | 12 ++++++++----
> >>  1 file changed, 8 insertions(+), 4 deletions(-)
> >>
> >> diff --git a/documentation/README b/documentation/README
> >> index f9e803a28b..1d4d213076 100644
> >> --- a/documentation/README
> >> +++ b/documentation/README
> >> @@ -328,11 +328,15 @@ The sphinx.ext.intersphinx extension is enabled
> by default
> >>  so that we can cross reference content from other Sphinx based
> >>  documentation projects, such as the BitBake manual.
> >>
> >> -References to the bitbake manual can be done like this:
> >> -
> >> -  See the ":ref:`-D
> <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`"
> option
> >> -or
> >> +References to the BitBake manual can be done:
> >> + - With a specific description instead of the section name:
> >> +  :ref:`Azure Storage fetcher (az://)
> <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
> >> + - With the section name:
> >> +  ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage
> and syntax` option
> >> + - With a BitBake variable name:
> >>    :term:`bitbake:BB_NUMBER_PARSE_THREADS`
> > I'd rather not specify bitbake: for terms so that they can be overriden
> > from within yocto-docs if need be, without needing to modify all the
> > refs spread over the whole git repo.
>
>
> Thanks for the feedback. However, I'm not sure what you mean here... Do
> you mean we should replace all instances of ":term:`bitbake:VARIABLE`"
> by ":term:`VARIABLE`"?
>

Yes. I think we already discussed that. I initially didn't like the idea,
but Quentin convinced me ;)


>
> If I understand well, if VARIABLE is only defined in the BitBake manual,
> we will directly get a reference in that manual.
>

When using :term:`FOO`, if FOO is defined in bitbake only, then the link
will be to the bitbake manual. If defined in both bitbake and yp-docs, then
it will link to yp-docs instead. Which is most likely what we always want
to do , if we ever need to override a term in yp-docs.


> Cheers,
> Michael.
>
> --
> Michael Opdenacker, Bootlin
> Embedded Linux and Kernel engineering
> https://bootlin.com
>
>
> 
>
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#1563): https://lists.yoctoproject.org/g/docs/message/1563
Mute This Topic: https://lists.yoctoproject.org/mt/84482573/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Michael Opdenacker July 27, 2021, 4:18 p.m.
Hi Nicolas,

On 7/27/21 5:00 PM, Nicolas Dechesne wrote:
>
>
> On Tue, Jul 27, 2021 at 4:29 PM Michael Opdenacker
> <michael.opdenacker@bootlin.com
> <mailto:michael.opdenacker@bootlin.com>> wrote:
>
>     Hi Quentin,
>
>     On 7/27/21 4:14 PM, Quentin Schulz wrote:
>     > Hi Michael,
>     >
>     > On Tue, Jul 27, 2021 at 04:11:59PM +0200, Michael Opdenacker wrote:
>     >> Signed-off-by: Michael Opdenacker
>     <michael.opdenacker@bootlin.com
>     <mailto:michael.opdenacker@bootlin.com>>
>     >> ---
>     >>  documentation/README | 12 ++++++++----
>     >>  1 file changed, 8 insertions(+), 4 deletions(-)
>     >>
>     >> diff --git a/documentation/README b/documentation/README
>     >> index f9e803a28b..1d4d213076 100644
>     >> --- a/documentation/README
>     >> +++ b/documentation/README
>     >> @@ -328,11 +328,15 @@ The sphinx.ext.intersphinx extension is
>     enabled by default
>     >>  so that we can cross reference content from other Sphinx based
>     >>  documentation projects, such as the BitBake manual.
>     >> 
>     >> -References to the bitbake manual can be done like this:
>     >> -
>     >> -  See the ":ref:`-D
>     <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and
>     syntax>`" option
>     >> -or
>     >> +References to the BitBake manual can be done:
>     >> + - With a specific description instead of the section name:
>     >> +  :ref:`Azure Storage fetcher (az://)
>     <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
>     >> + - With the section name:
>     >> + 
>     ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage
>     and syntax` option
>     >> + - With a BitBake variable name:
>     >>    :term:`bitbake:BB_NUMBER_PARSE_THREADS`
>     > I'd rather not specify bitbake: for terms so that they can be
>     overriden
>     > from within yocto-docs if need be, without needing to modify all the
>     > refs spread over the whole git repo.
>
>
>     Thanks for the feedback. However, I'm not sure what you mean
>     here... Do
>     you mean we should replace all instances of ":term:`bitbake:VARIABLE`"
>     by ":term:`VARIABLE`"?
>
>
> Yes. I think we already discussed that. I initially didn't like the
> idea, but Quentin convinced me ;)
>  
>
>
>     If I understand well, if VARIABLE is only defined in the BitBake
>     manual,
>     we will directly get a reference in that manual.
>
>
> When using :term:`FOO`, if FOO is defined in bitbake only, then the
> link will be to the bitbake manual. If defined in both bitbake and
> yp-docs, then it will link to yp-docs instead. Which is most likely
> what we always want to do , if we ever need to override a term in
> yp-docs.


Understood, I'll post an update that removes the explicit references to
the BitBake variables, but I'll still document how to make such a
reference, in case the needs arises one day.

Thanks!

Michael.