docs: dev-manual: fix typos, highlights, indentation and links

(From yocto-docs rev: ab244dcd48968ea6d0e328808c9aac4aef281032)

Signed-off-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/dev-manual/dev-manual-intro.rst

@@ -39,7 +39,7 @@ This manual does not provide the following:
 
 -  Reference or Conceptual Material: This type of material resides in an
    appropriate reference manual. For example, system variables are
-   documented in the :doc`../ref-manual/ref-manual`.
+   documented in the :doc:`../ref-manual/ref-manual`.
 
 -  Detailed Public Information Not Specific to the Yocto Project: For
    example, exhaustive information on how to use the Source Control

documentation/dev-manual/dev-manual-qemu.rst

@@ -33,10 +33,10 @@ implementation of QEMU.
 For official information and documentation on QEMU in general, see the
 following references:
 
--  `QEMU Website <http://wiki.qemu.org/Main_Page>`__\ *:* The official
+-  `QEMU Website <https://wiki.qemu.org/Main_Page>`__\ *:* The official
    website for the QEMU Open Source project.
 
--  `Documentation <http://wiki.qemu.org/Manual>`__\ *:* The QEMU user
+-  `Documentation <https://wiki.qemu.org/Manual>`__\ *:* The QEMU user
    manual.
 
 .. _qemu-running-qemu:
@@ -141,14 +141,14 @@ available. Follow these general steps to run QEMU:
 
    -  This example does not provide enough information for QEMU to
       launch. While the command does provide a root filesystem type, it
-      must also minimally provide a MACHINE, KERNEL, or VM option.
+      must also minimally provide a `MACHINE`, `KERNEL`, or `VM` option.
       ::
 
          $ runqemu ext4
 
    -  This example specifies to boot a virtual machine image
       (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
-      determines the QEMU architecture (MACHINE) to be "qemux86-64" and
+      determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
       the root filesystem type to be "vmdk".
       ::
 
@@ -208,7 +208,8 @@ using an NFS server.
    extracts it into a location that you specify. Here is an example that
    takes a file system and extracts it to a directory named
    ``test-nfs``:
-   ::
+
+   .. code-block:: none
 
       runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
 
@@ -217,7 +218,8 @@ using an NFS server.
    You can then also make changes to the files within ``./test-nfs`` and
    see those changes appear in the image in real time. Here is an
    example using the ``qemux86`` image:
-   ::
+
+   .. code-block:: none
 
       runqemu qemux86-64 ./test-nfs
 
@@ -226,14 +228,20 @@ using an NFS server.
    Should you need to start, stop, or restart the NFS share, you can use
    the following commands:
 
-   -  The following command starts the NFS share: runqemu-export-rootfs
+   -  The following command starts the NFS share:
-      start file-system-location
+      ::
 
-   -  The following command stops the NFS share: runqemu-export-rootfs
+         runqemu-export-rootfs start file-system-location
-      stop file-system-location
+
+   -  The following command stops the NFS share:
+      ::
+
+         runqemu-export-rootfs stop file-system-location
 
    -  The following command restarts the NFS share:
-      runqemu-export-rootfs restart file-system-location
+      ::
+
+         runqemu-export-rootfs restart file-system-location
 
 .. _qemu-kvm-cpu-compatibility:
 
@@ -380,30 +388,29 @@ command line:
 .. note::
 
    If you do provide some "illegal" option combination or perhaps you do
-   not provide enough in the way of options,
+   not provide enough in the way of options, ``runqemu``
-   runqemu
    provides appropriate error messaging to help you correct the problem.
 
--  QEMUARCH: The QEMU machine architecture, which must be "qemuarm",
+-  `QEMUARCH`: The QEMU machine architecture, which must be "qemuarm",
    "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
    "qemux86-64".
 
--  ``VM``: The virtual machine image, which must be a ``.wic.vmdk``
+-  `VM`: The virtual machine image, which must be a ``.wic.vmdk``
    file. Use this option when you want to boot a ``.wic.vmdk`` image.
    The image filename you provide must contain one of the following
    strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64",
    "qemumips", "qemuppc", or "qemush4".
 
--  ROOTFS: A root filesystem that has one of the following filetype
+-  `ROOTFS`: A root filesystem that has one of the following filetype
    extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If
    the filename you provide for this option uses "nfs", it must provide
    an explicit root filesystem path.
 
--  KERNEL: A kernel image, which is a ``.bin`` file. When you provide a
+-  `KERNEL`: A kernel image, which is a ``.bin`` file. When you provide a
    ``.bin`` file, ``runqemu`` detects it and assumes the file is a
    kernel image.
 
--  MACHINE: The architecture of the QEMU machine, which must be one of
+-  `MACHINE`: The architecture of the QEMU machine, which must be one of
    the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
    "qemumips", "qemumips64", or "qemuppc". The MACHINE and QEMUARCH
    options are basically identical. If you do not provide a MACHINE

documentation/dev-manual/dev-manual-start.rst

@@ -88,12 +88,10 @@ particular working environment and set of practices.
     .. note::
 
        For information about BitBake, see the
-       BitBake User Manual
+       :doc:`bitbake:index`.
-       .
 
     It is relatively easy to set up Git services and create
-    infrastructure like
+    infrastructure like :yocto_git:`/`, which is based on
-    :yocto_git:`http://git.yoctoproject.org <>`, which is based on
     server software called ``gitolite`` with ``cgit`` being used to
     generate the web interface that lets you view the repositories. The
     ``gitolite`` software identifies users using SSH keys and allows
@@ -106,10 +104,7 @@ particular working environment and set of practices.
        However, sites such as the following exist that describe how to
        perform setup:
 
-       -  `Git documentation <http://git-scm.com/book/ch4-8.html>`__:
+       -  `Gitolite <https://gitolite.com>`__: Information for
-          Describes how to install ``gitolite`` on the server.
-
-       -  `Gitolite <http://gitolite.com>`__: Information for
           ``gitolite``.
 
        -  `Interfaces, frontends, and
@@ -161,8 +156,7 @@ particular working environment and set of practices.
     integration" style testing of software components and regression
     identification and tracking.
 
-    See "`Yocto Project
+    See ":yocto_ab:`Yocto Project Autobuilder <>`" for more
-    Autobuilder <http://autobuilder.yoctoproject.org>`__" for more
     information and links to buildbot. The Yocto Project team has found
     this implementation works well in this role. A public example of
     this is the Yocto Project Autobuilders, which the Yocto Project team
@@ -207,8 +201,7 @@ particular working environment and set of practices.
 
     .. note::
 
-       You can also use a more collective push model. The
+       You can also use a more collective push model. The ``gitolite``
-       gitolite
        software supports both the push and pull models quite easily.
 
     As with any development environment, it is important to document the
@@ -285,11 +278,10 @@ v2 (WSL).
 .. note::
 
    The Yocto Project is not compatible with
-   Windows Subsystem for Linux v1
+   `Windows Subsystem for Linux v1 <https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`__.
-   . It is compatible but not officially supported nor validated with
+   It is compatible but not officially supported nor validated with
    WSLv2. If you still decide to use WSL please upgrade to
-   WSLv2
+   `WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__.
-   .
 
 Once your build host is set up to use the Yocto Project, further steps
 are necessary depending on what you want to accomplish. See the
@@ -453,9 +445,9 @@ as your Yocto Project build host:
 
 Once you have a container set up, everything is in place to develop just
 as if you were running on a native Linux machine. If you are going to
-use the Poky container, see the "`Cloning the ``poky``
+use the Poky container, see the
-Repository <#cloning-the-poky-repository>`__" section. If you are going
+":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
-to use the Extensible SDK container, see the
+section. If you are going to use the Extensible SDK container, see the
 ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you are going to use the Toaster container, see
@@ -566,10 +558,7 @@ your Yocto Project build host:
 
    The current implementation of WSLv2 does not have out-of-the-box
    access to external devices such as those connected through a USB
-   port, but it automatically mounts your
+   port, but it automatically mounts your ``C:`` drive on ``/mnt/c/``
-   C:
-   drive on
-   /mnt/c/
    (and others), which you can use to share deploy artifacts to be later
    flashed on hardware through Windows, but your build directory should
    not reside inside this mountpoint.
@@ -623,11 +612,8 @@ Use the following procedure to locate the latest upstream copy of the
 
    .. note::
 
-      For information on cloning a repository, see the "
+      For information on cloning a repository, see the
-      Cloning the
+      ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" section.
-      poky
-      Repository
-      " section.
 
 Accessing Index of Releases
 ---------------------------
@@ -653,12 +639,10 @@ Follow these steps to locate and download a particular tarball:
 
    .. note::
 
-      The
+      The ``yocto`` directory contains the full array of released Poky
-      yocto
+      tarballs. The ``poky`` directory in the Index of Releases was
-      directory contains the full array of released Poky tarballs. The
+      historically used for very early releases and exists now only for
-      poky
+      retroactive completeness.
-      directory in the Index of Releases was historically used for very
-      early releases and exists now only for retroactive completeness.
 
 2. *Select a Component:* Click on any released component in which you
    are interested (e.g. ``yocto``).
@@ -702,8 +686,7 @@ Releases <#accessing-index-of-releases>`__" section.
    .. note::
 
       For a "map" of Yocto Project releases to version numbers, see the
-      Releases
+      :yocto_wiki:`Releases </wiki/Releases>` wiki page.
-      wiki page.
 
    You can use the "RELEASE ARCHIVE" link to reveal a menu of all Yocto
    Project releases.
@@ -825,8 +808,9 @@ and then specifically check out that development branch.
 
 1. *Switch to the Poky Directory:* If you have a local poky Git
    repository, switch to that directory. If you do not have the local
-   copy of poky, see the "`Cloning the ``poky``
+   copy of poky, see the
-   Repository <#cloning-the-poky-repository>`__" section.
+   ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+   section.
 
 2. *Determine Existing Branch Names:*
    ::
@@ -854,13 +838,13 @@ and then specifically check out that development branch.
    &DISTRO; Release (&DISTRO_NAME;), use the following command:
    ::
 
-      $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+      $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
-      Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+      Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin.
-      Switched to a new branch '&DISTRO_NAME;'
+      Switched to a new branch '&DISTRO_NAME_NO_CAP;'
 
-   The previous command checks out the "&DISTRO_NAME;" development
+   The previous command checks out the "&DISTRO_NAME_NO_CAP;" development
    branch and reports that the branch is tracking the upstream
-   "origin/&DISTRO_NAME;" branch.
+   "origin/&DISTRO_NAME_NO_CAP;" branch.
 
    The following command displays the branches that are now part of your
    local poky repository. The asterisk character indicates the branch
@@ -868,8 +852,8 @@ and then specifically check out that development branch.
    ::
 
       $ git branch
-        master *
+        master
-        &DISTRO_NAME;
+        * &DISTRO_NAME_NO_CAP;
 
 .. _checkout-out-by-tag-in-poky:
 
@@ -889,8 +873,9 @@ similar to checking out by branch name except you use tag names.
 
 1. *Switch to the Poky Directory:* If you have a local poky Git
    repository, switch to that directory. If you do not have the local
-   copy of poky, see the "`Cloning the ``poky``
+   copy of poky, see the
-   Repository <#cloning-the-poky-repository>`__" section.
+   ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
+   section.
 
 2. *Fetch the Tag Names:* To checkout the branch based on a tag name,
    you need to fetch the upstream tags into your local repository: