Skip to content

doc: highlight BitBake snippets with the bitbake language

Trevor Woerner bitbake-devel yocto-docs 1 version New

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest4 patches 0 repliesNew

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4doc: bitbake-user-manual-metadata: use the bitbake code-block languagedoc/bitbake-user-manual/bitbake-user-manual-metadata.rst+279 -930 replies
2/4doc: bitbake-user-manual-ref-variables: use the bitbake code-block languagedoc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst+141 -470 replies
3/4doc: bitbake-user-manual-fetching: use the bitbake code-block languagedoc/bitbake-user-manual/bitbake-user-manual-fetching.rst+93 -310 replies
4/4doc: use the bitbake code-block language in the remaining chaptersdoc/bitbake-user-manual/bitbake-user-manual-execution.rst doc/bitbake-user-manual/bitbake-user-manual-hello.rst doc/bitbake-user-manual/bitbake-user-manual-intro.rst+66 -220 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

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

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(-)