diff mbox series

[RFC,2/2] BSP dev guide: update to use bitbake lexer

Message ID 20260421172416.1801567-3-twoerner@gmail.com
State Under Review
Headers show
Series support bitbake blocks | expand

Commit Message

Trevor Woerner April 21, 2026, 5:24 p.m. UTC 
From: Trevor Woerner <trevor.woerner@amd.com>

Identify all bitbake blocks, re-categorize them as "code-blocks" and set
their language as "bitbake".

10 highlighted BitBake blocks emitted in the rendered HTML, matching
the 10 code-block:: bitbake directives now in bsp.rst. Build completed
with the same 189 pre-existing warnings (all intersphinx / cross- ref
related, none from these changes).

Edits

In documentation/bsp-guide/bsp.rst, I converted every snippet that
is actually BitBake metadata from a plain literal block (::) to ..
code-block:: bitbake. Shell transcripts, directory listings, and prose-
following :: blocks were left alone. The 10 converted blocks are:

  1. BBLAYERS ?= ... example near the BSP-layer overview.
  2. The expanded BBLAYERS example covering container layers like
     meta-openembedded/meta-oe.
  3. The boilerplate conf/layer.conf (BBPATH, BBFILES,
     BBFILE_COLLECTIONS, LAYERDEPENDS_bsp).
  4. The Raspberry Pi conf/layer.conf excerpt with LICENSE_PATH.
  5. The include conf/machine/include/rpi-base.inc directive in
     raspberrypi3.conf.
  6. The PREFERRED_PROVIDER_virtual/kernel /
     PREFERRED_VERSION_linux-yocto snippet in the kernel-recipe section.
  7. The FILESEXTRAPATHS:prepend := "${THISDIR}/files:" example in the
     customizing-a-recipe walkthrough.
  8. The Beaglebone conf/layer.conf shown in "BSP Layer Configuration
     Example".
  9. The Beaglebone PREFERRED_PROVIDER_virtual/kernel /
     PREFERRED_VERSION_linux-yocto snippet in "BSP Kernel Recipe Example".
 10. The linux-yocto_6.1.bbappend body (KBRANCH:*, KMACHINE:*,
     SRCREV_machine:*, COMPATIBLE_MACHINE:*, LINUX_VERSION:*).

The directory-listing block at line 290 stays as code-block:: none
(it is a filesystem tree, not BitBake), and the formfactor machconfig
snippet (HAVE_TOUCHSCREEN=0 etc.) is intentionally left as a plain
literal block since it is shell-style key=value, not BitBake syntax.

Verification

  make (python3 -m sphinx -b html ... . _build/html) completes with
  exit 0 and build succeeded, 189 warnings, identical to the pre-change
  baseline; none of those warnings reference bsp.rst line numbers I
  touched, the new bitbake extension, or Pygments lexing. Spot-checking
  the rendered HTML shows 10 highlight-bitbake Pygments-highlighted
  blocks in documentation/_build/html/bsp-guide/bsp.html, matching the 10
  directives.

AI-Generated: codex/claude-opus 4.7 (xhigh)
Signed-off-by: Trevor Woerner <trevor.woerner@amd.com>
---
 documentation/bsp-guide/bsp.rst | 40 ++++++++++++++++++++++++---------
 1 file changed, 30 insertions(+), 10 deletions(-)
diff mbox series

Patch

diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst
index a3b57d29f9e6..67dd9a67d651 100644
--- a/documentation/bsp-guide/bsp.rst
+++ b/documentation/bsp-guide/bsp.rst
@@ -84,7 +84,9 @@  established after you run the OpenEmbedded build environment setup
 script (i.e. :ref:`structure-core-script`).
 Adding the root directory allows the :term:`OpenEmbedded Build System`
 to recognize the BSP
-layer and from it build an image. Here is an example::
+layer and from it build an image. Here is an example:
+
+.. code-block:: bitbake
 
    BBLAYERS ?= " \
       /usr/local/src/yocto/meta \
@@ -112,7 +114,9 @@  are known as ":term:`container layers <Container Layer>`". An example of
 this type of layer is OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
 layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers.
 In cases like this, you need to include the names of the actual layers
-you want to work with, such as::
+you want to work with, such as:
+
+.. code-block:: bitbake
 
    BBLAYERS ?= " \
      /usr/local/src/yocto/meta \
@@ -531,7 +535,9 @@  identifies the contents of the layer, and contains information about how
 the build system should use it. Generally, a standard boilerplate file
 such as the following works. In the following example, you would replace
 "bsp" with the actual name of the BSP (i.e. "bsp_root_name" from the example
-template). ::
+template).
+
+.. code-block:: bitbake
 
    # We have a conf and classes directory, add to BBPATH
    BBPATH .= ":${LAYERDIR}"
@@ -546,7 +552,9 @@  template). ::
    LAYERDEPENDS_bsp = "intel"
 
 To illustrate the string substitutions, here are the corresponding
-statements from the Raspberry Pi ``conf/layer.conf`` file::
+statements from the Raspberry Pi ``conf/layer.conf`` file:
+
+.. code-block:: bitbake
 
    # We have a conf and classes directory, append to BBPATH
    BBPATH .= ":${LAYERDIR}"
@@ -603,7 +611,9 @@  For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``,
 
 To use an include file, you simply include them in the machine
 configuration file. For example, the Raspberry Pi BSP
-``raspberrypi3.conf`` contains the following statement::
+``raspberrypi3.conf`` contains the following statement:
+
+.. code-block:: bitbake
 
    include conf/machine/include/rpi-base.inc
 
@@ -674,7 +684,9 @@  Suppose you are using the ``linux-yocto_6.12.bb`` recipe to build the
 kernel. In other words, you have selected the kernel in your
 ``"bsp_root_name".conf`` file by adding
 :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION`
-statements as follows::
+statements as follows:
+
+.. code-block:: bitbake
 
    PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
    PREFERRED_VERSION_linux-yocto ?= "6.12%"
@@ -1027,7 +1039,9 @@  BSP-specific configuration file named ``interfaces`` to the
 also supports several other machines:
 
 #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the
-   following::
+   following:
+
+   .. code-block:: bitbake
 
       FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
 
@@ -1195,7 +1209,9 @@  BSP Layer Configuration Example
 -------------------------------
 
 The layer's ``conf`` directory contains the ``layer.conf`` configuration
-file. In this example, the ``conf/layer.conf`` file is the following::
+file. In this example, the ``conf/layer.conf`` file is the following:
+
+.. code-block:: bitbake
 
    # We have a conf and classes directory, add to BBPATH
    BBPATH .= ":${LAYERDIR}"
@@ -1375,7 +1391,9 @@  BSP Kernel Recipe Example
 -------------------------
 
 The kernel recipe used to build the kernel image for the BeagleBone
-device was established in the machine configuration::
+device was established in the machine configuration:
+
+.. code-block:: bitbake
 
    PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
    PREFERRED_VERSION_linux-yocto ?= "6.1%"
@@ -1386,7 +1404,9 @@  metadata used to build the kernel. In this case, a kernel append file
 kernel recipe (i.e. ``linux-yocto_6.1.bb``), which is located in
 :oe_git:`/openembedded-core/tree/meta/recipes-kernel/linux`.
 
-The contents of the append file are::
+The contents of the append file are:
+
+.. code-block:: bitbake
 
    KBRANCH:genericx86  = "v6.1/standard/base"
    KBRANCH:genericx86-64  = "v6.1/standard/base"