Re: [docs] [PATCH 13/34] ref-manual: add pressure limit variable documentation

Michael Opdenacker
2022-10-17T08:32:02Z

Hi Quentin

On 10/17/22 10:26, Quentin Schulz wrote:
> Hi all,
>
> On 10/17/22 10:15, Michael Opdenacker via lists.yoctoproject.org wrote:
>> Hi Paul,
>>
>> On 10/16/22 22:38, Paul Eggleton wrote:
>>> On Tuesday, 11 October 2022 23:30:50 NZDT Michael Opdenacker via
>>> lists.yoctoproject.org wrote:
>>>> Actually, these have recently been accepted in the BitBake manual (the
>>>> patches from Aryaman got accepted after he left WindRiver), though
>>>> apparently with fewer details:
>>>> https://urldefense.proofpoint.com/v2/url?u=https-3A__git.openembedded.org_bitbake_commit_-3Fid-3Dc014281f72f4f54ec8e681ef2b8e&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=x6GN6XCgxQmI7f-H7T3WT3-Fm0BA5lJwsTI4AYj7vqNo4vO7FONFXbwhZxNDjOg5&s=w3C2EZQkLelO9mCiJE4ey-FVbNc3zA7PBHZ2nnBc4wE&e=
>>>> 1080de9ab5cf
>>>>
>>>> Shall we submit your updates to the Bitbake manual instead? This
>>>> way, we
>>>> don't have these variables documented in two different places.
>>> Ah, oops - I missed that. I'm OK with that for now; however, and I
>>> may have
>>> also missed if this has been discussed recently, but it's my opinion
>>> that all
>>> variables documented in the BitBake manual should also be in the Yocto
>>> reference manual, since they are two different contexts - the catch
>>> being that
>>> for some variables there is information you can't reasonably include
>>> in the
>>> bitbake manual since it relies on some definitions unique to OE so
>>> the entries
>>> can't always be copied exactly. If on the other hand some variables
>>> only
>>> appear in the BitBake manual, there will be people who just won't
>>> find them.
>>
>>
>> I agree that BitBake variables should all appear in the Yocto
>> variable index.
>>
>> There are already some variables which are initially documented in
>> the BitBake manual and then the description is expanded in the Yocto
>> manual according to the OE additions. SRC_URI is one of them:
>>
>>   *
>> https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_bitbake_2.0_bitbake-2Duser-2Dmanual_bitbake-2Duser-2Dmanual-2Dref-2Dvariables.html-23term-2DSRC-5FURI&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=x6GN6XCgxQmI7f-H7T3WT3-Fm0BA5lJwsTI4AYj7vqNo4vO7FONFXbwhZxNDjOg5&s=MUG2hR2Xp_pBuwrtNxNwKRKxCuWXh8fgIcmZm7k0cTw&e=
>>  *
>> https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_ref-2Dmanual_variables.html-23term-2DSRC-5FURI&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=x6GN6XCgxQmI7f-H7T3WT3-Fm0BA5lJwsTI4AYj7vqNo4vO7FONFXbwhZxNDjOg5&s=jTk77XY6-zxpJ_a9dWSexbLvlpev2lr2-QfhnWYv74E&e=
>>>
>>> To avoid things getting out of sync, we could potentially have a
>>> script that
>>> would check for and report on variables present in the BitBake
>>> manual that
>>> aren't in the Yocto reference manual. I'd be happy to write such a
>>> script.
>>
>
> This would be a good start, though...
>
>>
>> This would be useful, but if I recall correctly, Quentin was rather
>> thinking about having Sphinx include these from the BitBake manual,
>> at least for the ones which are only defined in the BitBake manual.
>>
>
> I'd prefer having a Sphinx plugin that does this automatically (I
> haven't checked if this is actually possible).
>
> But we can start with this script and manually adding those to the YP
> glossary. Someone may eventually find the time and motivation to look
> into a Sphinx plugin but I for sure don't have this time at the
> moment. sorry.
>
> How do you think of implementing this? I had in mind to just add a
> variable in the glossary whose description would be:
>
> See :term:`BitBake documentation <bitbake:FOOVAR>`
>
> so we don't need to take care of keeping their description in sync,

Yes, this would be perfectly acceptable as a first solution IMHO, if
nobody objects this redirection. Then Paul's script would definitely
help (thanks in advance!).
Cheers
Michael.

--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering