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

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

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
version of pygments, so backporting patches that use the bitbake lexer won't be
an issue (from an Autobuilder perspective).

>> Sure, this is more efforts and review time, but also this is how other markup
>> languages work - like markdown, where by default (when using ```...```) no
>> syntax highlighting is done.
>> > This is maybe a more conservative approach but at least it doesn't 
> leave room
>> for code blocks mistakenly highlighted with the bitbake lexer.
>> 
>
> It's currently mistakenly highlighted in Python if it looks like Python 
> to pygments (the default).
>
> It's the Yocto/Bitbake documentation, I'm assuming the overwhelming 
> majority of code-blocks should be BitBake code.
>
> If you really want to require explicit lexers, then set
>
> highlight_language = "please_specify_the_highlight_language_for_this_block"
>
> in conf.py and then everybody will have to set one.
>
> Again, if you explicitly use the bitbake lexer in master, you won't be 
> able to backport those patches to stable branches easily. Or you'll need 
> your users to update their build environments to use the new release of 
> pygments.

We can add a requirement on pygments:

diff --git a/documentation/tools/host_packages_scripts/pip3_docs.sh b/documentation/tools/host_packages_scripts/pip3_docs.sh
index 852845783..d7a983731 100644
--- a/documentation/tools/host_packages_scripts/pip3_docs.sh
+++ b/documentation/tools/host_packages_scripts/pip3_docs.sh
@@ -1,3 +1,3 @@
 python3 -m venv --clear ./yocto-docs-venv
 . ./yocto-docs-venv/bin/activate
-python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0'
+python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0' 'pygments>=2.21.0'

And backport it to Wrynose/Scarthgap?

> Or maybe you want to write a custom bitbake lexer for stable 
> branches that is an alias to the "default" (the default value of 
> highlight_language) lexer, but only have it if the version of pygments 
> doesn't contain a bitbake lexer already.

This could be an alternative, yes.

Quoting your other email (https://lore.kernel.org/r/66624f77-ae0d-4670-bd99-c6ea9d2b2a54@cherry.de):

> Sphinx explicitly states that Python will be tried and if there are
> highlights warnings, none will be used. c.f.
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples

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.

Thanks,
Antonin