Skip to content

docs: highlight BitBake snippets with the bitbake language

Trevor Woerner yocto-docs 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest10 patches 22 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/10ref-manual/variables.rst: use the bitbake code-block languagedocumentation/ref-manual/variables.rst+1226 -4090 replies
2/10ref-manual: use the bitbake code-block languagedocumentation/ref-manual/classes.rst documentation/ref-manual/devtool-reference.rst documentation/ref-manual/faq.rst +3 more+183 -610 replies
3/10dev-manual: use the bitbake code-block languagedocumentation/dev-manual/bblock.rst documentation/dev-manual/bmaptool.rst documentation/dev-manual/build-quality.rst +32 more+522 -1760 replies
4/10migration-guides: use the bitbake code-block languagedocumentation/migration-guides/migration-1.3.rst documentation/migration-guides/migration-1.6.rst documentation/migration-guides/migration-1.7.rst +24 more+236 -790 replies
5/10kernel-dev: use the bitbake code-block languagedocumentation/kernel-dev/advanced.rst documentation/kernel-dev/common.rst documentation/kernel-dev/faq.rst+108 -360 replies
6/10test-manual: use the bitbake code-block languagedocumentation/test-manual/intro.rst documentation/test-manual/ptest.rst documentation/test-manual/reproducible-builds.rst +1 more+66 -220 replies
7/10overview-manual: use the bitbake code-block languagedocumentation/overview-manual/concepts.rst+51 -170 replies
8/10security-manual: use the bitbake code-block languagedocumentation/security-manual/read-only-rootfs.rst documentation/security-manual/securing-images.rst documentation/security-manual/sstate-signing.rst +1 more+48 -160 replies
9/10sdk-manual: use the bitbake code-block languagedocumentation/sdk-manual/appendix-customizing-standard.rst documentation/sdk-manual/appendix-customizing.rst+11 -90 replies
10/10docs-wide: use the bitbake code-block languagedocumentation/brief-yoctoprojectqs/index.rst documentation/bsp-manual/bsp.rst documentation/contributor-guide/recipe-style-guide.rst +1 more+54 -180 replies

Reviews trailers per patch

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

Read the v1 thread

Cover letter [PATCH 00/10] docs: 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. 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 matching. Blocks that share BitBake's assignment shape but are another language were left alone: a Makefile, Django settings, an Automake fragment, a wic kickstart include, kernel .scc metadata, U-Boot Image Tree Source. So were blocks an author had deliberately marked "none", which usually means "this is not purely code" rather than "nobody got round to it".

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

"docs: state the language of nine literal blocks explicitly", sent separately, which gives some non-BitBake blocks their correct language. 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.

Not included
------------

Six blocks in ref-manual/ trip a defect in the released BitBake lexer, fixed upstream but not yet in a release. They are a separate patch, held until that release, so the rest is not blocked behind them.

Trevor Woerner (10):
ref-manual/variables.rst: use the bitbake code-block language
ref-manual: use the bitbake code-block language
dev-manual: use the bitbake code-block language
migration-guides: use the bitbake code-block language
kernel-dev: use the bitbake code-block language
test-manual: use the bitbake code-block language
overview-manual: use the bitbake code-block language
security-manual: use the bitbake code-block language
sdk-manual: use the bitbake code-block language
docs-wide: use the bitbake code-block language

 documentation/brief-yoctoprojectqs/index.rst  |    4 +-
 documentation/bsp-manual/bsp.rst              |   28 +-
 .../contributor-guide/recipe-style-guide.rst  |   24 +-
 documentation/dev-manual/bblock.rst           |    4 +-
 documentation/dev-manual/bmaptool.rst         |    4 +-
 documentation/dev-manual/build-quality.rst    |    8 +-
 documentation/dev-manual/building.rst         |   44 +-
 .../dev-manual/creating-fragments.rst         |    6 +-
 .../dev-manual/custom-distribution.rst        |    4 +-
 .../dev-manual/customizing-images.rst         |   32 +-
 documentation/dev-manual/debugging.rst        |   40 +-
 documentation/dev-manual/device-manager.rst   |   12 +-
 documentation/dev-manual/devtool.rst          |    8 +-
 documentation/dev-manual/disk-space.rst       |    4 +-
 .../dev-manual/error-reporting-tool.rst       |   12 +-
 documentation/dev-manual/external-scm.rst     |   20 +-
 .../dev-manual/gobject-introspection.rst      |   12 +-
 documentation/dev-manual/hashequivserver.rst  |   12 +-
 documentation/dev-manual/init-manager.rst     |   16 +-
 documentation/dev-manual/layers.rst           |   56 +-
 documentation/dev-manual/libraries.rst        |   12 +-
 documentation/dev-manual/licenses.rst         |   60 +-
 .../dev-manual/limiting-resources.rst         |    4 +-
 documentation/dev-manual/multiconfig.rst      |   40 +-
 documentation/dev-manual/new-machine.rst      |    4 +-
 documentation/dev-manual/new-recipe.rst       |  160 +-
 documentation/dev-manual/packages.rst         |   44 +-
 .../dev-manual/poky-manual-setup.rst          |    4 +-
 .../dev-manual/prebuilt-libraries.rst         |   12 +-
 documentation/dev-manual/qemu.rst             |    4 +-
 documentation/dev-manual/quilt.rst            |    4 +-
 documentation/dev-manual/sbom.rst             |    4 +-
 .../dev-manual/speeding-up-build.rst          |    4 +-
 .../dev-manual/sstate-mirrors-setup.rst       |   16 +-
 .../dev-manual/temporary-source-code.rst      |    8 +-
 .../dev-manual/upgrading-recipes.rst          |   12 +-
 documentation/dev-manual/wayland.rst          |    8 +-
 documentation/dev-manual/x32-psabi.rst        |    4 +-
 documentation/kernel-dev/advanced.rst         |   48 +-
 documentation/kernel-dev/common.rst           |   88 +-
 documentation/kernel-dev/faq.rst              |    8 +-
 .../migration-guides/migration-1.3.rst        |    8 +-
 .../migration-guides/migration-1.6.rst        |   12 +-
 .../migration-guides/migration-1.7.rst        |    4 +-
 .../migration-guides/migration-1.8.rst        |   12 +-
 .../migration-guides/migration-2.0.rst        |    8 +-
 .../migration-guides/migration-2.1.rst        |    4 +-
 .../migration-guides/migration-2.2.rst        |   11 +-
 .../migration-guides/migration-2.3.rst        |   12 +-
 .../migration-guides/migration-2.5.rst        |    4 +-
 .../migration-guides/migration-2.6.rst        |   12 +-
 .../migration-guides/migration-3.0.rst        |    4 +-
 .../migration-guides/migration-3.1.rst        |   12 +-
 .../migration-guides/migration-3.2.rst        |    8 +-
 .../migration-guides/migration-3.3.rst        |    8 +-
 .../migration-guides/migration-3.4.rst        |   16 +-
 .../migration-guides/migration-4.0.rst        |   12 +-
 .../migration-guides/migration-4.1.rst        |    8 +-
 .../migration-guides/migration-4.2.rst        |   12 +-
 .../migration-guides/migration-5.1.rst        |   12 +-
 .../migration-guides/migration-5.2.rst        |   24 +-
 .../migration-guides/migration-5.3.rst        |   36 +-
 .../migration-guides/migration-6.0.rst        |   44 +-
 .../migration-guides/migration-6.1.rst        |   12 +-
 .../migration-guides/release-notes-4.0.rst    |    4 +-
 .../migration-guides/release-notes-4.3.rst    |    4 +-
 .../migration-guides/release-notes-5.0.rst    |    4 +-
 .../migration-guides/release-notes-5.3.rst    |    8 +-
 documentation/overview-manual/concepts.rst    |   68 +-
 documentation/profile-manual/intro.rst        |   16 +-
 documentation/ref-manual/classes.rst          |  168 +-
 .../ref-manual/devtool-reference.rst          |    4 +-
 documentation/ref-manual/faq.rst              |   20 +-
 documentation/ref-manual/features.rst         |   12 +-
 documentation/ref-manual/qa-checks.rst        |   20 +-
 documentation/ref-manual/tasks.rst            |   20 +-
 documentation/ref-manual/variables.rst        | 1635 ++++++++++++-----
 .../appendix-customizing-standard.rst         |    4 +-
 .../sdk-manual/appendix-customizing.rst       |   16 +-
 .../security-manual/read-only-rootfs.rst      |    8 +-
 .../security-manual/securing-images.rst       |    8 +-
 .../security-manual/sstate-signing.rst        |   16 +-
 .../security-manual/vulnerabilities.rst       |   32 +-
 documentation/test-manual/intro.rst           |    4 +-
 documentation/test-manual/ptest.rst           |   24 +-
 .../test-manual/reproducible-builds.rst       |    8 +-
 documentation/test-manual/runtime-testing.rst |   52 +-
 87 files changed, 2505 insertions(+), 843 deletions(-)