[PATCH] dev-manual: fix references to BitBake user manual

[PATCH] dev-manual: fix references to BitBake user manual

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Fix a wrong reference
Add missing double quotes in a reference to a chapter title

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/common-tasks.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index ca6d594386..7b9fdac10c 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -2563,7 +2563,7 @@ Recipe Syntax
 Understanding recipe file syntax is important for writing recipes. The
 following list overviews the basic items that make up a BitBake recipe
 file. For more complete BitBake syntax descriptions, see the
-":doc:`bitbake-user-manual/bitbake-user-manual-metadata`"
+":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`"
 chapter of the BitBake User Manual.
 
 -  *Variable Assignments and Manipulations:* Variable assignments allow
@@ -2621,7 +2621,7 @@ chapter of the BitBake User Manual.
 This next list summarizes the most important and most commonly used
 parts of the recipe syntax. For more information on these parts of the
 syntax, you can reference the
-:doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata` chapter
+":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`" chapter
 in the BitBake User Manual.
 
 -  *Line Continuation (\\):* Use the backward slash (``\``) character to
-- 
2.34.1

Re: [docs] [PATCH] dev-manual: fix references to BitBake user manual

[Quentin Schulz]

Hi Michael,

On 6/10/22 19:17, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> Fix a wrong reference
> Add missing double quotes in a reference to a chapter title
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/dev-manual/common-tasks.rst | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index ca6d594386..7b9fdac10c 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -2563,7 +2563,7 @@ Recipe Syntax
>   Understanding recipe file syntax is important for writing recipes. The
>   following list overviews the basic items that make up a BitBake recipe
>   file. For more complete BitBake syntax descriptions, see the
> -":doc:`bitbake-user-manual/bitbake-user-manual-metadata`"
> +":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`"

I don't understand why this is required? Sphinx should find this link 
just fine in the objects.inv from the Bitbake docs if I remember 
correctly? Is this just to have the same "convention" (since we already 
have links using bitbake: in front) or is this actually fixing a bug 
somehow?

If the link was broken, we need to work on running checklinks when 
building the docs so we're aware when links are broken or outdated. 
Well, it's anyways a good idea :)

Cheers,
Quentin

Re: [docs] [PATCH] dev-manual: fix references to BitBake user manual

[Quentin Schulz]

Hi Michael,

On 6/13/22 10:56, Michael Opdenacker wrote:
> Hi Quentin
> 
> On 6/13/22 10:19, Quentin Schulz wrote:
>> Hi Michael,
>>
>> On 6/10/22 19:17, Michael Opdenacker via lists.yoctoproject.org wrote:
>>> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>>
>>> Fix a wrong reference
>>> Add missing double quotes in a reference to a chapter title
>>>
>>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>> ---
>>>   documentation/dev-manual/common-tasks.rst | 4 ++--
>>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/documentation/dev-manual/common-tasks.rst 
>>> b/documentation/dev-manual/common-tasks.rst
>>> index ca6d594386..7b9fdac10c 100644
>>> --- a/documentation/dev-manual/common-tasks.rst
>>> +++ b/documentation/dev-manual/common-tasks.rst
>>> @@ -2563,7 +2563,7 @@ Recipe Syntax
>>>   Understanding recipe file syntax is important for writing recipes. The
>>>   following list overviews the basic items that make up a BitBake recipe
>>>   file. For more complete BitBake syntax descriptions, see the
>>> -":doc:`bitbake-user-manual/bitbake-user-manual-metadata`"
>>> +":doc:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata`"
>>
>> I don't understand why this is required? Sphinx should find this link 
>> just fine in the objects.inv from the Bitbake docs if I remember 
>> correctly? Is this just to have the same "convention" (since we 
>> already have links using bitbake: in front) or is this actually fixing 
>> a bug somehow?
>>
>> If the link was broken, we need to work on running checklinks when 
>> building the docs so we're aware when links are broken or outdated. 
>> Well, it's anyways a good idea :)
> 
> 
> Thanks for the review. I should have given details. Actually, that link 
> was missing "bitbake:" at the beginning. I don't know how it worked 
> before switching to Sphinx 5.0.1, but at least it wasn't compliant with 
> our guidelines (in the documentation/README file) to add a "bitbake:" 
> prefix to references to the BitBake user manual.
> 

FYI, the :doc: directive does not look into intersphinx references 
anymore since 5.0.0, c.f. 
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes. 
This behavior can be changed and reverted to pre-5.0 behavior with the 
intersphinx_disabled_reftypes variable set in conf.py.

As opposed to :term: which I feel like benefits from the ability to 
fallback to bitbake intersphinx term definition if not defined in 
yocto-docs, I am not so sure about going back to pre-5.0 behavior for 
the :doc: directive. It seems likely we can have collisions in names and 
I think it's not desired?

Cheers,
Quentin