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

[Quentin Schulz <quentin.schulz@theobroma-systems.com>]

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