mbox series

[0/4] doc: highlight BitBake snippets with the bitbake language

Message ID 20260826013703.2674786-1-twoerner@gmail.com
Headers show
Series doc: highlight BitBake snippets with the bitbake language | expand

Message

Trevor Woerner Aug. 26, 2026, 1:36 a.m. UTC 
Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
what they are instead of rendering as plain literal blocks. The user
manual is where the language is documented, so it seemed the wrong place
to leave unhighlighted.

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. Blocks that share
BitBake's assignment shape but are another language were left alone,
including the bitbake-setup settings files, which are INI and already
tagged as such.

Please do not apply this yet
----------------------------

The autobuilder builds the docs with a pinned buildtools tarball that
currently carries Pygments 2.19.2, which predates the BitBake lexer.
run-docs-build also passes SPHINXOPTS="-j auto", dropping the -W the
Makefile defaults to, so on that toolchain every one of these blocks
would publish unhighlighted and the build would still succeed. I have
asked separately about refreshing that tarball.

Sending now for review rather than to be merged. Once the toolchain can
render it, this applies as-is.

Depends on
----------

"doc: state the language of six Python blocks explicitly", sent
separately. That patch stands on its own and can go in independently;
this series is based on it only so the two do not touch the same lines.

One block worth a second opinion
--------------------------------

bitbake-user-manual-ref-variables.rst has two blocks where one real
assignment is followed by a long prose "where: ..." explanation. I have
tagged them, but the same shape elsewhere was deliberately left as a
plain literal block, so I may have called this one wrong.

Trevor Woerner (4):
  doc: bitbake-user-manual-metadata: use the bitbake code-block language
  doc: bitbake-user-manual-ref-variables: use the bitbake code-block
    language
  doc: bitbake-user-manual-fetching: use the bitbake code-block language
  doc: use the bitbake code-block language in the remaining chapters

 .../bitbake-user-manual-execution.rst         |  44 ++-
 .../bitbake-user-manual-fetching.rst          | 124 ++++--
 .../bitbake-user-manual-hello.rst             |  20 +-
 .../bitbake-user-manual-intro.rst             |  24 +-
 .../bitbake-user-manual-metadata.rst          | 372 +++++++++++++-----
 .../bitbake-user-manual-ref-variables.rst     | 188 ++++++---
 6 files changed, 579 insertions(+), 193 deletions(-)