1 files changed, 24 insertions, 11 deletions

diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.rst b/documentation/kernel-dev/kernel-dev-maint-appx.rst
index 0b0cca14a7..5514dac876 100644
--- a/documentation/kernel-dev/kernel-dev-maint-appx.rst
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.rst
@@ -28,12 +28,17 @@ in the Yocto Project Linux kernel in any clone of the Yocto Project
 Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For
 example, the following commands clone the Yocto Project baseline Linux
 kernel that branches off ``linux.org`` version 4.12 and the
-``yocto-kernel-cache``, which contains stores of kernel Metadata: $ git
-clone git://git.yoctoproject.org/linux-yocto-4.12 $ git clone
-git://git.yoctoproject.org/linux-kernel-cache For more information on
+``yocto-kernel-cache``, which contains stores of kernel Metadata:
+::
+
+   $ git clone git://git.yoctoproject.org/linux-yocto-4.12
+   $ git clone git://git.yoctoproject.org/linux-kernel-cache
+
+For more information on
 how to set up a local Git repository of the Yocto Project Linux kernel
-files, see the "`Preparing the Build Host to Work on the
-Kernel <#preparing-the-build-host-to-work-on-the-kernel>`__" section.
+files, see the
+":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
+section.
 
 Once you have cloned the kernel Git repository and the cache of Metadata
 on your local machine, you can discover the branches that are available
@@ -41,10 +46,13 @@ in the repository using the following Git command: $ git branch -a
 Checking out a branch allows you to work with a particular Yocto Linux
 kernel. For example, the following commands check out the
 "standard/beagleboard" branch of the Yocto Linux kernel repository and
-the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: $ cd
-~/linux-yocto-4.12 $ git checkout -b my-kernel-4.12
-remotes/origin/standard/beagleboard $ cd ~/linux-kernel-cache $ git
-checkout -b my-4.12-metadata remotes/origin/yocto-4.12
+the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:
+::
+
+   $ cd ~/linux-yocto-4.12
+   $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard
+   $ cd ~/linux-kernel-cache
+   $ git checkout -b my-4.12-metadata remotes/origin/yocto-4.12
 
 .. note::
 
@@ -102,7 +110,9 @@ patch, or BSP:
    For a typical build, the target of the search is a feature
    description in an ``.scc`` file whose name follows this format (e.g.
    ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):
-   bsp_root_name-kernel_type.scc
+   ::
+
+      bsp_root_name-kernel_type.scc
 
 3. *Expand Feature:* Once located, the feature description is either
    expanded into a simple script of actions, or into an existing
@@ -212,7 +222,10 @@ build process generates a build tree that is separate from your kernel's
 local Git source repository tree. This build tree has a name that uses
 the following form, where ``${MACHINE}`` is the metadata name of the
 machine (BSP) and "kernel_type" is one of the Yocto Project supported
-kernel types (e.g. "standard"): linux-${MACHINE}-kernel_type-build
+kernel types (e.g. "standard"):
+::
+
+   linux-${MACHINE}-kernel_type-build
 
 The existing support in the ``kernel.org`` tree achieves this default
 functionality.