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

[Trevor Woerner <twoerner@gmail.com>]

On Wed 2026-08-26 @ 03:09:23 PM, Antonin Godard wrote:
> Hi,
> 
> On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> > Hi Trevor,
> >
> > On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:
> >> Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
> >> what they are instead of rendering as plain literal blocks. This tags
> >> the ones in yocto-docs.
> >> 
> >> One patch per manual, which is also roughly one reviewable unit per
> >> patch. No prose changes, no reflowing, no reindenting - every hunk turns
> >> a literal-block introducer into a code-block directive and nothing else.
> >> 
> >> Which blocks were converted was decided by reading, not by pattern
> >
> > "by reading" following a paragraph definitely not written by you and 
> > with all commits being AI-Generated is quite the stretch ;)

When I asked AI to add explicit code-blocks with explicit language tags
I emphasized it should read the entire block before deciding. At work I
am the head of a massive project to convert some of our documentation
from wiki to reST and was caught a couple times by this.

Bitbake syntax has a tendency to sometimes look like bash, and sometimes
look like python, so I wanted to make sure AI was being careful about
the languages it was guessing.

In fact I pushed back on some of the choices when it selected python
instead of bitbake, but then it pushed back on me and said: "yes it's a
bitbake example, but this code snippet is entirely python" and in some
rare cases it was actually correct.

So this "by reading" statement was probably AI's way of saying: "i was
careful about the choices i made", rather than implying that "Trevor
read each one and decided".

> >
> > [...]
> >
> >> Depends on
> >> ----------
> >> 
> >> "docs: state the language of nine literal blocks explicitly", sent
> >
> > Link to the ML please to make maintainers and reviewers job easier.
> >
> > [...]
> >
> > 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?
> 
> 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.

Yes, I agree too.  Personally I'm not fond of "hidden defaults".

By default a non-specified block will cause pygments to guess. So if I'm
looking at a lot of reST and seeing no tags, I'm going to assume the
authors have left pygments to guess. I would have to go looking in other
places to see if there's a default in place for non-specified code-block
tags, which I'm probably not going to think of doing, which will
sometimes probably cause more confusion before it becomes clear.

Maybe it's just me, but I prefer to see every example block using an
explicit code-block tag and specifying a language. That way the author's
intentions are unambiguous, and we have an expected output.

That's what I've enforced for our reST at work, and I've also
differentiated between "bash" (for actual shell programs) versus
"console" (for interactive work at a shell prompt, a shell most likely
to be bash).