Skip to contentSkip to conversation

docs: state the language of nine literal blocks explicitly

PATCH Applied Trevor Woerner 2 participants 2 messages Aug 26 – Sep 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: state the language of nine literal blocks explicitly

Nine blocks carry no language, so Sphinx falls back to "default". That is not the same as being unhighlighted, and not the same as being right
either: "default" is the Python lexer, and when it raises, the block is dropped silently to "none" where a named language would warn.

except ErrorToken as err:
if lang == 'default':
lang = 'none' # automatic highlighting failed.
else:
logger.warning('Lexing literal_block %r as "%s" resulted in
an error at token: %r ...')

So a block that happens to be valid Python is highlighted by accident, and stops being highlighted the moment an edit makes it not-quite-valid, with nothing to say so. Naming the language turns that silence into a warning, which -W surfaces to whoever made the edit.

Two of the three cases also render differently right away:

ref-manual/variables.rst three U-Boot Image Tree Source blocks,
introduced as "the following FIT source". This is device-tree syntax; guessing Python finds roughly two thirds of the tokens.
overview-manual/concepts.rst a Makefile, introduced as "the contents
of sayhello/Makefile". Guessing Python raises, so today it renders with no highlighting at all.
test-manual/intro.rst five unittest classes quoted from
bitbake/lib/bb/tests/data.py and meta/lib/oeqa/. They use BitBake's own API, but they are Python source files rather than metadata, and they already render correctly; the change is that they now say so.

Each language was chosen by lexing the block and comparing the result, not by eye. Two plausible alternatives were rejected on that evidence:
yaml renders the FIT blocks as one flat scalar run, and make emits per-character error tokens on kernel .scc syntax, so the .scc blocks are left alone here.

AI-Generated: codex/claude-opus 5 (xhigh)

---
 documentation/overview-manual/concepts.rst |  4 +++-
 documentation/ref-manual/variables.rst     | 12 +++++++++---
 documentation/test-manual/intro.rst        | 20 +++++++++++++++-----
 3 files changed, 27 insertions(+), 9 deletions(-)
documentation/overview-manual/concepts.rst +3 -1
index 73a24d8d301b..d4530e97fed9 100644
@@ -2296,7 +2296,9 @@ The contents of ``libhello/hellolib.c`` are::
       puts("Hello from a Yocto demo \n");
    }
 
-The contents of ``sayhello/Makefile`` are::
+The contents of ``sayhello/Makefile`` are:
+
+.. code-block:: make
 
    EXEC=sayhello
    LDFLAGS += -lhello
documentation/ref-manual/variables.rst +9 -3
index fa0dfdfb87f2..646a77982646 100644
@@ -3667,7 +3667,9 @@ system and gives an overview of their function and contents.
          FIT_LOADABLE_OS[tee] = "tee"
          FIT_LOADABLE_LOADADDRESS[tee] = "0x96000000"
 
-      and will be converted to the following FIT source::
+      and will be converted to the following FIT source:
+
+      .. code-block:: devicetree
 
          images {
                  atf {
@@ -11745,7 +11747,9 @@ system and gives an overview of their function and contents.
       https://fitspec.osfw.foundation/\ .
 
       The original content of the U-Boot Image Tree Source (ITS) is as
-      follows::
+      follows:
+
+      .. code-block:: devicetree
 
          images {
              uboot {
@@ -11782,7 +11786,9 @@ system and gives an overview of their function and contents.
       ``\n``.
 
       The generated content of the U-Boot Image Tree Source (ITS) is as
-      follows::
+      follows:
+
+      .. code-block:: devicetree
 
          images {
              uboot {
documentation/test-manual/intro.rst +15 -5
index 0868abe8c3c4..4ddc9851f824 100644
@@ -325,7 +325,9 @@ This section provides example tests for each of the tests listed in the
 ``bitbake-selftest``
 --------------------
 
-A simple test example from ``bitbake/lib/bb/tests/data.py`` is::
+A simple test example from ``bitbake/lib/bb/tests/data.py`` is:
+
+.. code-block:: python
 
    class DataExpansions(unittest.TestCase):
       def setUp(self):
@@ -358,7 +360,9 @@ for full builds. Rather than directly using `Python unittest
 <https://docs.python.org/3/library/unittest.html>`__, the code
 wraps most of the standard objects. The tests can be simple, such as
 testing a command from within the OE build environment using the
-following example::
+following example:
+
+.. code-block:: python
 
    class BitbakeLayers(OESelftestTestCase):
       def test_bitbakelayers_showcrossdepends(self):
@@ -401,7 +405,9 @@ These tests are run once an image is up and running, either on target
 hardware or under QEMU. As a result, they are assumed to be running in a
 target image environment, as opposed to in a host build environment. A
 simple example from ``meta/lib/oeqa/runtime/cases/python.py`` contains
-the following::
+the following:
+
+.. code-block:: python
 
    class PythonTest(OERuntimeTestCase):
       @OETestDepends(['ssh.SSHTest.test_ssh'])
@@ -427,7 +433,9 @@ the image.
 
 These tests are run against built extensible SDKs (eSDKs). The tests can
 assume that the eSDK environment has already been set up. An example from
-``meta/lib/oeqa/sdk/cases/devtool.py`` contains the following::
+``meta/lib/oeqa/sdk/cases/devtool.py`` contains the following:
+
+.. code-block:: python
 
    class DevtoolTest(OESDKExtTestCase):
       @classmethod def setUpClass(cls):
@@ -460,7 +468,9 @@ the ``devtool build`` command within the eSDK.
 These tests are run against built SDKs. The tests can assume that an SDK
 has already been extracted and its environment file has been sourced. A
 simple example from ``meta/lib/oeqa/sdk/cases/python.py`` contains the
-following::
+following:
+
+.. code-block:: python
 
    class Python3Test(OESDKTestCase):
       def setUp(self):
#1 lore raw

Applied, thanks!

[1/1] docs: state the language of nine literal blocks explicitly

      commit: 9437982143f2f6bcf521841c02559ab4331aae6b