[PATCH v2 7/8] kernel-dev: give each example block one thing to hold

[Trevor Woerner <twoerner@gmail.com>]

Several kernel metadata examples put a filename label inside the block,
and some go on to hold more than one file, in more than one language,
under a single "::". A block shaped that way is not any one language, so
it can only ever be shown unhighlighted.

Split them into a block each, dedent what is left, and move the
filename to the code-block caption, which keeps it attached to the block
it names and renders it inside the block's frame. The theme centres a
caption in italics, which reads as prose, so it is restyled to look like
the filename it is.

AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- the caption takes the theme's whole font stack; the shortened copy
  dropped Liberation Mono, which is why it rendered in a different face
---
 documentation/kernel-dev/advanced.rst         | 139 ++++++++++--------
 .../sphinx-static/theme_overrides.css         |  28 ++++
 2 files changed, 104 insertions(+), 63 deletions(-)

diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index 321033b7bd49..ecd0137fa5fd 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -216,24 +216,28 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the
 recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
 two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
 ``cfg`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository::
+``yocto-kernel-cache`` Git repository.
+
+.. code-block::
+   :caption: cfg/smp.scc
+
+   define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
+   define KFEATURE_COMPATIBILITY all
 
-   cfg/smp.scc:
-      define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
-      define KFEATURE_COMPATIBILITY all
+   kconf hardware smp.cfg
 
-      kconf hardware smp.cfg
+.. code-block::
+   :caption: cfg/smp.cfg
 
-   cfg/smp.cfg:
-      CONFIG_SMP=y
-      CONFIG_SCHED_SMT=y
-      # Increase default NR_CPUS from 8 to 64 so that platform with
-      # more than 8 processors can be all activated at boot time
-      CONFIG_NR_CPUS=64
-      # The following is needed when setting NR_CPUS to something
-      # greater than 8 on x86 architectures, it should be automatically
-      # disregarded by Kconfig when using a different arch
-      CONFIG_X86_BIGSMP=y
+   CONFIG_SMP=y
+   CONFIG_SCHED_SMT=y
+   # Increase default NR_CPUS from 8 to 64 so that platform with
+   # more than 8 processors can be all activated at boot time
+   CONFIG_NR_CPUS=64
+   # The following is needed when setting NR_CPUS to something
+   # greater than 8 on x86 architectures, it should be automatically
+   # disregarded by Kconfig when using a different arch
+   CONFIG_X86_BIGSMP=y
 
 You can find general information on configuration
 fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
@@ -278,36 +282,39 @@ kernel as defined outside of the recipe space (i.e.
 in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
 ``yocto-kernel-cache`` Git repository.
 
-The following listings show the ``build.scc`` file and part of the
-``modpost-mask-trivial-warnings.patch`` file::
+.. code-block::
+   :caption: patches/build/build.scc
 
-   patches/build/build.scc:
-      patch arm-serialize-build-targets.patch
-      patch powerpc-serialize-image-targets.patch
-      patch kbuild-exclude-meta-directory-from-distclean-processi.patch
+   patch arm-serialize-build-targets.patch
+   patch powerpc-serialize-image-targets.patch
+   patch kbuild-exclude-meta-directory-from-distclean-processi.patch
 
-      # applied by kgit
-      # patch kbuild-add-meta-files-to-the-ignore-li.patch
+   # applied by kgit
+   # patch kbuild-add-meta-files-to-the-ignore-li.patch
 
-      patch modpost-mask-trivial-warnings.patch
-      patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
+   patch modpost-mask-trivial-warnings.patch
+   patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
 
-   patches/build/modpost-mask-trivial-warnings.patch:
-      From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
-      From: Paul Gortmaker <paul.gortmaker@windriver.com>
-      Date: Sun, 25 Jan 2009 17:58:09 -0500
-      Subject: [PATCH] modpost: mask trivial warnings
+and part of the patch it names:
 
-      Newer HOSTCC will complain about various stdio fcns because
-                        .
-                        .
-                        .
-                char *dump_write = NULL, *files_source = NULL;
-                int opt;
-      --
-      2.10.1
+.. code-block::
+   :caption: patches/build/modpost-mask-trivial-warnings.patch
 
-      generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
+   From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
+   From: Paul Gortmaker <paul.gortmaker@windriver.com>
+   Date: Sun, 25 Jan 2009 17:58:09 -0500
+   Subject: [PATCH] modpost: mask trivial warnings
+
+   Newer HOSTCC will complain about various stdio fcns because
+                     .
+                     .
+                     .
+             char *dump_write = NULL, *files_source = NULL;
+             int opt;
+   --
+   2.10.1
+
+   generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
 
 The description file can
 include multiple patch statements where each statement handles a single
@@ -325,16 +332,18 @@ Features
 
 Features are complex kernel Metadata types that consist of configuration
 fragments, patches, and possibly other feature description files. As an
-example, consider the following generic listing::
+example, consider the following generic listing:
+
+.. code-block::
+   :caption: features/myfeature.scc
 
-   features/myfeature.scc
-      define KFEATURE_DESCRIPTION "Enable myfeature"
+   define KFEATURE_DESCRIPTION "Enable myfeature"
 
-      patch 0001-myfeature-core.patch
-      patch 0002-myfeature-interface.patch
+   patch 0001-myfeature-core.patch
+   patch 0002-myfeature-interface.patch
 
-      include cfg/myfeature_dependency.scc
-      kconf non-hardware myfeature.cfg
+   include cfg/myfeature_dependency.scc
+   kconf non-hardware myfeature.cfg
 
 This example shows how the ``patch`` and ``kconf`` commands are used as well
 as how an additional feature description file is included with the
@@ -873,17 +882,19 @@ new branch as the :term:`KBRANCH` to use for the board as follows::
    KBRANCH = "mynewbranch"
 
 Another method is to use the ``branch`` command in the BSP
-description::
+description:
 
-   mybsp.scc:
-      define KMACHINE mybsp
-      define KTYPE standard
-      define KARCH i386
-      include standard.scc
+.. code-block::
+   :caption: mybsp.scc
 
-      branch mynewbranch
+   define KMACHINE mybsp
+   define KTYPE standard
+   define KARCH i386
+   include standard.scc
+
+   branch mynewbranch
 
-      include mybsp-hw.scc
+   include mybsp-hw.scc
 
 If you find yourself with numerous branches, you might consider using a
 hierarchical branching system similar to what the Yocto Linux Kernel Git
@@ -925,18 +936,20 @@ that have to be regularly updated. The Yocto Project Linux kernel tools
 provide for this with the ``git merge`` command.
 
 To merge a feature branch into a BSP, insert the ``git merge`` command
-after any ``branch`` commands::
+after any ``branch`` commands:
 
-   mybsp.scc:
-      define KMACHINE mybsp
-      define KTYPE standard
-      define KARCH i386
-      include standard.scc
+.. code-block::
+   :caption: mybsp.scc
+
+   define KMACHINE mybsp
+   define KTYPE standard
+   define KARCH i386
+   include standard.scc
 
-      branch mynewbranch
-      git merge myfeature
+   branch mynewbranch
+   git merge myfeature
 
-      include mybsp-hw.scc
+   include mybsp-hw.scc
 
 SCC Description File Reference
 ==============================
diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
index f9e067239b8e..3912872e1890 100644
--- a/documentation/sphinx-static/theme_overrides.css
+++ b/documentation/sphinx-static/theme_overrides.css
@@ -107,6 +107,34 @@ section#welcome-to-the-yocto-project-documentation p.caption {
    display: none;
 }
 
+/* A code-block caption names the file the block came from, so it
+   should read as a filename rather than as prose, and sit on the block
+   it titles rather than floating above it. */
+.rst-content .literal-block-wrapper .code-block-caption {
+    font-style: normal;
+    font-family: SFMono-Regular, Menlo, Monaco, Consolas,
+                 Liberation Mono, Courier New, Courier, monospace;
+    font-size: 80%;
+    text-align: left;
+    color: #e6edf3;
+    background: #2b3137;
+    padding: .45em .9em;
+    margin: 0;
+    line-height: 1.5;
+    border-radius: 4px 4px 0 0;
+}
+
+.rst-content .literal-block-wrapper .code-block-caption .headerlink {
+    color: #93a1ad;
+}
+
+/* No gap and no doubled border between a caption and its block. */
+.rst-content .literal-block-wrapper .code-block-caption + div[class^=highlight] {
+    margin-top: 0;
+    border-top: none;
+    border-radius: 0 0 4px 4px;
+}
+
 @media screen {
     .wy-nav-content {
        max-width: 1000px;
-- 
2.50.0.173.g8b6f19ccfc3a