Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language

["Antonin Godard" <antonin.godard@bootlin.com>]

On Wed Aug 26, 2026 at 5:43 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>
>
> On 8/26/26 5:10 PM, Antonin Godard wrote:
>> Hi,
>> 
>> On Wed Aug 26, 2026 at 4:34 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>>
>>>
>>> On 8/26/26 3:09 PM, Antonin Godard wrote:
>> [...]
>>>>> I think this is going the wrong direction. We should actually make
>>>>> explicit the language of every :: that is NOT to be understood as
>>>>> BitBake code and then make the default highlight language be BitBake.
>>>>
>>>> But then this might get forgotten? How about having the default highlighted as
>>>> "none", and make _everything_ use explicit code-blocks?
>>>>
>>>
>>> """
>>> The direct benefit is the ability to still backport whatever needs to be
>>> backported without having to care about the highlight language being
>>> explicitly bitbake (which won't be available in every branch but master).
>>> """
>>>
>>> *exactly* the sentence after what you quoted.
>>>
>>> It's bound to happen someone will want to backport a patch with
>>>
>>> .. code-block:: bitbake
>>>
>>> Either we'll forget during review and it'll break the docs build, or we
>>> need to adapt each and every patch/commit for stable branches.
>>>
>>> I'm usually the one trying to add friction to processes, but I don't
>>> think the above is a good idea.
>>>
>>> I'm trying to avoid having code-blocks set to use the bitbake lexer so
>>> we can easily backport without having to care.
>> 
>> Our current active releases where we backport patches are Wrynose and Scarthgap.
>> Both use the same buildtools tarball on the Autobuilder, and contain the same
>
> But should they? Aren't we supposed to build the docs with an SDK we 
> build from the same branch as the one from the docs?

It's been like this for a while now, and has not caused issues. I'm afraid
maintaining several SDKs for each branch would be a bit painful, although it's
probably the "right" thing to do.

[...]
>> This is interesting! If it behaves the same way with whatever highlight_language
>> you set in conf.py, then this would be less of an issue I guess.
>> 
>
> I don't know for sure without looking at Sphinx's source code but my 
> reading of the docs says "no", this is specific to "default" 
> (highlight_language = "default", which is the default value if absent).
>
> highlight_block() in sphinx/highlighting.py has a check when there's a 
> parsing error to use none if the language is currently "default". 
> Reading a bit further down, there's a check on the force flag. I'm 
> assuming this comes from :force: from rST, so I'm not sure whether we 
> can actually pass it by default (and in any case, we would still have a 
> big fat warning, which we don't with the "default" value).
>
> "default" seems to be a synonym of Python in get_lexer() as well, so not 
> sure we can simply decide "actually, no rather bitbake instead of python 
> lexer".
>
> I haven't had a deeper look than that into Sphinx source code.

I've tested it directly: setting highlight_language to "bitbake" would produce
errors in case Sphinx fails to highlight a code-block.

Antonin