doc: state the language of six Python blocks explicitly
PATCH 1/1 doc: state the language of six Python blocks explicitly
Six blocks show BitBake datastore and library calls - d.getVar, d.getVarFlags, bb.fetch2.Fetch, bb.fatal - written in Python, and carry no language:
fetching.rst "the code to execute the first part of this
process", the fetcher instantiation and the two unpack calls
metadata.rst the BB_ORIGENV datastore example and the
getVarFlags/setVarFlags pair
library-functions.rst the f-string example, introduced with
"Python f-strings may also be used"
These are BitBake snippets, but "bitbake" is the wrong language for them. In a recipe this code lives inside a python task, and the BitBake lexer hands task bodies to the Python lexer; wrapping each of these in a python task and comparing tokens by offset gives a result identical to lexing it as Python directly. Presented as a bare block instead, the BitBake lexer reads each line as a variable assignment at column 0 and renders d.getVar( as part of a string value. BitBake's own parser agrees it is not an assignment: there is no quoted value, so it would be a parse error. So "python" is what the BitBake lexer itself produces for this code in the context where it belongs.
Nothing renders differently today. Sphinx maps an untagged block to "default", which is the Python lexer, so these are already highlighted - by accident. The difference is what happens when that lexer raises:
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 ...')
"default" is dropped silently to "none"; a named language warns, and -W puts that in front of whoever made the edit. Naming the language turns a guess that happens to be right into a statement that stays checked.
AI-Generated: codex/claude-opus 5 (xhigh)
--- .../bitbake-user-manual-fetching.rst | 12 +++++++++--- .../bitbake-user-manual-library-functions.rst | 4 +++- .../bitbake-user-manual-metadata.rst | 8 ++++++-- 3 files changed, 18 insertions(+), 6 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +9 -3
@@ -27,7 +27,9 @@ and unpacking the files is often optionally followed by patching. Patching, however, is not covered by this module. The code to execute the first part of this process, a fetch, looks -something like the following:: +something like the following: + +.. code-block:: python src_uri = (d.getVar('SRC_URI') or "").split() fetcher = bb.fetch2.Fetch(src_uri, d)
@@ -37,7 +39,9 @@ This code sets up an instance of the fetch class. The instance uses a space-separated list of URLs from the :term:`SRC_URI` variable and then calls the ``download`` method to download the files. -The instantiation of the fetch class is usually followed by:: +The instantiation of the fetch class is usually followed by: + +.. code-block:: python rootdir = l.getVar('UNPACKDIR') fetcher.unpack(rootdir)
@@ -203,7 +207,9 @@ that updates an existing checkout *in place* rather than removing and re-cloning it. This is useful when the target directory may contain local commits that should be preserved across updates. -The code to call the non-destructive update looks like the following:: +The code to call the non-destructive update looks like the following: + +.. code-block:: python rootdir = l.getVar('UNPACKDIR') fetcher.unpack_update(rootdir)
doc/bitbake-user-manual/bitbake-user-manual-library-functions.rst +3 -1
@@ -29,7 +29,9 @@ Formatted string can also be used directly:: bb.error("%s, we have a %s" % ("Houston", "big problem")) -Python f-strings may also be used:: +Python f-strings may also be used: + +.. code-block:: python h = "Houston" bb.fatal(f"{h}, we have a critical problem")
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +6 -2
@@ -1719,7 +1719,9 @@ environment into a special variable named :term:`BB_ORIGENV`. The :term:`BB_ORIGENV` variable returns a datastore object that can be queried using the standard datastore operators such as ``getVar(, False)``. The datastore object is useful, for example, to -find the original ``DISPLAY`` variable. Here is an example:: +find the original ``DISPLAY`` variable. Here is an example: + +.. code-block:: python origenv = d.getVar("BB_ORIGENV", False) bar = origenv.getVar("BAR", False)
@@ -1732,7 +1734,9 @@ Variable Flags Variable flags (varflags) help control a task's functionality and dependencies. BitBake reads and writes varflags to the datastore using -the following command forms:: +the following command forms: + +.. code-block:: python variable = d.getVarFlags("variable") self.d.setVarFlags("FOO", {"func": True})
Quoted 11 lines · Trevor Woerner via lists.yoctoproject.org
Six blocks show BitBake datastore and library calls - d.getVar, d.getVarFlags, bb.fetch2.Fetch, bb.fatal - written in Python, and carry no language:
fetching.rst"the code to execute the first part of this
process", the fetcher instantiation and the two unpack calls
metadata.rsttheBB_ORIGENVdatastore example and the
getVarFlags/setVarFlags pair
library-functions.rstthe f-string example, introduced with
"Python f-strings may also be used"
[...]
Thanks!
Antonin