sphinx: brief-yoctoprojectqs: fix up all remaining rendering issues

Manual fix up for links, references, code-block, formatting issues..

(From yocto-docs rev: b0c5333c0f9321cdc1f46e1637cd5e9faf6b42a2)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.rst

@@ -16,12 +16,12 @@ build a reference embedded OS called Poky.
 
    -  The examples in this paper assume you are using a native Linux
       system running a recent Ubuntu Linux distribution. If the machine
-      you want to use Yocto Project on to build an image (`build
+      you want to use Yocto Project on to build an image
-      host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__) is not
+      (:term:`Build Host`) is not
       a native Linux system, you can still perform these steps by using
       CROss PlatformS (CROPS) and setting up a Poky container. See the
-      `Setting Up to Use CROss PlatformS
+      :ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`
-      (CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section
+      section
       in the Yocto Project Development Tasks Manual for more
       information.
 
@@ -34,48 +34,41 @@ build a reference embedded OS called Poky.
          compatible but not officially supported nor validated with
          WSLv2, if you still decide to use WSL please upgrade to WSLv2.
 
-      See the `Setting Up to Use Windows Subsystem For
+      See the :ref:`dev-manual/dev-manual-start:setting up to use windows
-      Linux <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl>`__" section in
+      subsystem for linux (wslv2)` section in the Yocto Project Development
-      the Yocto Project Development Tasks Manual for more information.
+      Tasks Manual for more information.
 
 If you want more conceptual or background information on the Yocto
-Project, see the `Yocto Project Overview and Concepts
+Project, see the :doc:`../overview-manual/overview-manual`.
-Manual <&YOCTO_DOCS_OM_URL;>`__.
 
 Compatible Linux Distribution
 =============================
 
-Make sure your `build
+Make sure your :term:`Build Host` meets the
-host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ meets the
 following requirements:
 
 -  50 Gbytes of free disk space
 
 -  Runs a supported Linux distribution (i.e. recent releases of Fedora,
    openSUSE, CentOS, Debian, or Ubuntu). For a list of Linux
-   distributions that support the Yocto Project, see the "`Supported
+   distributions that support the Yocto Project, see the
-   Linux
+   :ref:`ref-manual/ref-system-requirements:supported linux distributions`
-   Distributions <&YOCTO_DOCS_REF_URL;#detailed-supported-distros>`__"
    section in the Yocto Project Reference Manual. For detailed
-   information on preparing your build host, see the "`Preparing the
+   information on preparing your build host, see the
-   Build Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__"
+   :ref:`dev-manual/dev-manual-start:preparing the build host`
    section in the Yocto Project Development Tasks Manual.
 
 -
 
    -  Git 1.8.3.1 or greater
-
    -  tar 1.28 or greater
-
    -  Python 3.5.0 or greater.
-
    -  gcc 5.0 or greater.
 
    If your build host does not meet any of these three listed version
    requirements, you can take steps to prepare the system so that you
-   can still use the Yocto Project. See the "`Required Git, tar, Python
+   can still use the Yocto Project. See the
-   and gcc
+   :ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`
-   Versions <&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions>`__"
    section in the Yocto Project Reference Manual for information.
 
 Build Host Packages
@@ -88,38 +81,71 @@ distribution:
 .. note::
 
    For host package requirements on all supported Linux distributions,
-   see the "
+   see the :ref:`ref-manual/ref-system-requirements:required packages for the build host`
-   Required Packages for the Build Host
+   section in the Yocto Project Reference Manual.
-   " section in the Yocto Project Reference Manual.
 
-$ sudo apt-get install UBUNTU_HOST_PACKAGES_ESSENTIAL
+.. code-block:: shell
+
+  $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
 
 Use Git to Clone Poky
 =====================
 
 Once you complete the setup instructions for your machine, you need to
 get a copy of the Poky repository on your build host. Use the following
-commands to clone the Poky repository. $ git clone
+commands to clone the Poky repository.
-git://git.yoctoproject.org/poky Cloning into 'poky'... remote: Counting
+
-objects: 432160, done. remote: Compressing objects: 100%
+.. code-block:: shell
-(102056/102056), done. remote: Total 432160 (delta 323116), reused
+
-432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81
+   $ git clone git://git.yoctoproject.org/poky
-MiB \| 8.54 MiB/s, done. Resolving deltas: 100% (323116/323116), done.
+   Cloning into 'poky'...
-Checking connectivity... done. Move to the ``poky`` directory and take a
+   remote: Counting
-look at the tags: $ cd poky $ git fetch --tags $ git tag 1.1_M1.final
+   objects: 432160, done. remote: Compressing objects: 100%
-1.1_M1.rc1 1.1_M1.rc2 1.1_M2.final 1.1_M2.rc1 . . . yocto-2.5
+   (102056/102056), done. remote: Total 432160 (delta 323116), reused
-yocto-2.5.1 yocto-2.5.2 yocto-2.6 yocto-2.6.1 yocto-2.6.2 yocto-2.7
+   432037 (delta 323000) Receiving objects: 100% (432160/432160), 153.81 MiB \| 8.54 MiB/s, done.
-yocto_1.5_M5.rc8 For this example, check out the branch based on the
+   Resolving deltas: 100% (323116/323116), done.
-DISTRO_REL_TAG release: $ git checkout tags/DISTRO_REL_TAG -b
+   Checking connectivity... done.
-my-DISTRO_REL_TAG Switched to a new branch 'my-DISTRO_REL_TAG' The
+
-previous Git checkout command creates a local branch named
+Move to the ``poky`` directory and take a look at the tags:
-my-DISTRO_REL_TAG. The files available to you in that branch exactly
+
-match the repository's files in the "DISTRO_NAME_NO_CAP" development
+.. code-block:: shell
-branch at the time of the Yocto Project DISTRO_REL_TAG release.
+
+   $ cd poky
+   $ git fetch --tags
+   $ git tag
+   1.1_M1.final
+   1.1_M1.rc1
+   1.1_M1.rc2
+   1.1_M2.final
+   1.1_M2.rc1
+   .
+   .
+   .
+   yocto-2.5
+   yocto-2.5.1
+   yocto-2.5.2
+   yocto-2.6
+   yocto-2.6.1
+   yocto-2.6.2
+   yocto-2.7
+   yocto_1.5_M5.rc8
+
+For this example, check out the branch based on the
+&DISTRO_REL_TAG; release:
+
+.. code-block:: shell
+
+   $ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG;
+   Switched to a new branch 'my-&DISTRO_REL_TAG;'
+
+The previous Git checkout command creates a local branch named
+my-&DISTRO_REL_TAG;. The files available to you in that branch exactly
+match the repository's files in the "&DISTRO_NAME_NO_CAP;" development
+branch at the time of the Yocto Project &DISTRO_REL_TAG; release.
 
 For more options and information about accessing Yocto Project related
-repositories, see the "`Locating Yocto Project Source
+repositories, see the
-Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
+:ref:`dev-manual/dev-manual-start:locating yocto project source files`
 section in the Yocto Project Development Tasks Manual.
 
 Building Your Image
@@ -142,35 +168,51 @@ an entire Linux distribution, including the toolchain, from source.
       ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`"
       page of the Yocto Project Wiki.
 
-1. *Initialize the Build Environment:* From within the ``poky``
+#. **Initialize the Build Environment:** From within the ``poky``
-   directory, run the
+   directory, run the :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``
-   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment
+   environment
    setup script to define Yocto Project's build environment on your
-   build host. $ cd ~/poky $ source OE_INIT_FILE You had no
+   build host.
-   conf/local.conf file. This configuration file has therefore been
-   created for you with some default values. You may wish to edit it to,
-   for example, select a different MACHINE (target hardware). See
-   conf/local.conf for more information as common configuration options
-   are commented. You had no conf/bblayers.conf file. This configuration
-   file has therefore been created for you with some default values. To
-   add additional metadata layers into your configuration please add
-   entries to conf/bblayers.conf. The Yocto Project has extensive
-   documentation about OE including a reference manual which can be
-   found at: http://yoctoproject.org/documentation For more information
-   about OpenEmbedded see their website: http://www.openembedded.org/
-   ### Shell environment set up for builds. ### You can now run 'bitbake
-   <target>' Common targets are: core-image-minimal core-image-sato
-   meta-toolchain meta-ide-support You can also run generated qemu
-   images with a command like 'runqemu qemux86-64' Among other things,
-   the script creates the
-   :term:`Build Directory`, which is
-   ``build`` in this case and is located in the :term:`Source Directory`.
-   After the
-   script runs, your current working directory is set to the Build
-   Directory. Later, when the build completes, the Build Directory
-   contains all the files created during the build.
 
-2. *Examine Your Local Configuration File:* When you set up the build
+   .. code-block:: shell
+
+      $ cd ~/poky
+      $ source &OE_INIT_FILE;
+      You had no conf/local.conf file. This configuration file has therefore been
+      created for you with some default values. You may wish to edit it to, for
+      example, select a different MACHINE (target hardware). See conf/local.conf
+      for more information as common configuration options are commented.
+
+      You had no conf/bblayers.conf file. This configuration file has therefore
+      been created for you with some default values. To add additional metadata
+      layers into your configuration please add entries to conf/bblayers.conf.
+
+      The Yocto Project has extensive documentation about OE including a reference
+      manual which can be found at:
+          http://yoctoproject.org/documentation
+
+      For more information about OpenEmbedded see their website:
+          http://www.openembedded.org/
+
+      ### Shell environment set up for builds. ###
+
+      You can now run 'bitbake <target>'
+
+      Common targets are:
+          core-image-minimal
+          core-image-sato
+          meta-toolchain
+          meta-ide-support
+
+      You can also run generated qemu images with a command like 'runqemu qemux86-64'
+
+   Among other things, the script creates the :term:`Build Directory`, which is
+   ``build`` in this case and is located in the :term:`Source Directory`.  After
+   the script runs, your current working directory is set to the Build
+   Directory. Later, when the build completes, the Build Directory contains all the
+   files created during the build.
+
+#. **Examine Your Local Configuration File:** When you set up the build
    environment, a local configuration file named ``local.conf`` becomes
    available in a ``conf`` subdirectory of the Build Directory. For this
    example, the defaults are set to build for a ``qemux86`` target,
@@ -179,44 +221,47 @@ an entire Linux distribution, including the toolchain, from source.
 
    .. tip::
 
-      You can significantly speed up your build and guard against
+      You can significantly speed up your build and guard against fetcher
-      fetcher failures by using mirrors. To use mirrors, add these lines
+      failures by using mirrors. To use mirrors, add these lines to your
-      to your
+      local.conf file in the Build directory: ::
-      local.conf
-      file in the Build directory:
-      ::
 
-              SSTATE_MIRRORS = "\
+         SSTATE_MIRRORS = "\
-              file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
+         file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
-              file://.* http://sstate.yoctoproject.org/YOCTO_DOC_VERSION_MINUS_ONE/PATH;downloadfilename=PATH \n \
+         file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
-              file://.* http://sstate.yoctoproject.org/YOCTO_DOC_VERSION/PATH;downloadfilename=PATH \n \
+         file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
-              "
+         "
 
 
-      The previous examples showed how to add sstate paths for Yocto
+      The previous examples showed how to add sstate paths for Yocto Project
-      Project YOCTO_DOC_VERSION_MINUS_ONE, YOCTO_DOC_VERSION, and a
+      &YOCTO_DOC_VERSION_MINUS_ONE;, &YOCTO_DOC_VERSION;, and a development
-      development area. For a complete index of sstate locations, see
+      area. For a complete index of sstate locations, see http://sstate.yoctoproject.org/.
-      .
 
-3. *Start the Build:* Continue with the following command to build an OS
+#. **Start the Build:** Continue with the following command to build an OS
-   image for the target, which is ``core-image-sato`` in this example: $
+   image for the target, which is ``core-image-sato`` in this example:
-   bitbake core-image-sato For information on using the ``bitbake``
-   command, see the
-   "`BitBake <&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake>`__"
-   section in the Yocto Project Overview and Concepts Manual, or see the
-   ":ref:`BitBake Command <bitbake:bitbake-user-manual-command>`" section
-   in the BitBake User Manual.
 
-4. *Simulate Your Image Using QEMU:* Once this particular image is
+   .. code-block:: shell
+
+      $ bitbake core-image-sato
+
+   For information on using the ``bitbake`` command, see the
+   :ref:`usingpoky-components-bitbake` section in the Yocto Project Overview and
+   Concepts Manual, or see the ":ref:`BitBake Command
+   <bitbake:bitbake-user-manual-command>`" section in the BitBake User Manual.
+
+#. **Simulate Your Image Using QEMU:** Once this particular image is
    built, you can start QEMU, which is a Quick EMUlator that ships with
-   the Yocto Project: $ runqemu qemux86-64 If you want to learn more
+   the Yocto Project:
-   about running QEMU, see the "`Using the Quick EMUlator
-   (QEMU) <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__" chapter in the
-   Yocto Project Development Tasks Manual.
 
-5. *Exit QEMU:* Exit QEMU by either clicking on the shutdown icon or by
+   .. code-block:: shell
-   typing ``Ctrl-C`` in the QEMU transcript window from which you evoked
+
-   QEMU.
+      $ runqemu qemux86-64
+
+   If you want to learn more about running QEMU, see the
+   :ref:`dev-manual/dev-manual-qemu:using the quick emulator (qemu)` chapter in
+   the Yocto Project Development Tasks Manual.
+
+#. **Exit QEMU:** Exit QEMU by either clicking on the shutdown icon or by typing
+   ``Ctrl-C`` in the QEMU transcript window from which you evoked QEMU.
 
 Customizing Your Build for Specific Hardware
 ============================================
@@ -237,25 +282,33 @@ modular development and makes it easier to reuse the layer metadata.
 
 Follow these steps to add a hardware layer:
 
-1. *Find a Layer:* Lots of hardware layers exist. The Yocto Project
+#. **Find a Layer:** Lots of hardware layers exist. The Yocto Project
    :yocto_git:`Source Repositories <>` has many hardware layers.
    This example adds the
    `meta-altera <https://github.com/kraj/meta-altera>`__ hardware layer.
 
-2. *Clone the Layer* Use Git to make a local copy of the layer on your
+#. **Clone the Layer** Use Git to make a local copy of the layer on your
    machine. You can put the copy in the top level of the copy of the
-   Poky repository created earlier: $ cd ~/poky $ git clone
+   Poky repository created earlier:
-   https://github.com/kraj/meta-altera.git Cloning into 'meta-altera'...
+
-   remote: Counting objects: 25170, done. remote: Compressing objects:
+   .. code-block:: shell
-   100% (350/350), done. remote: Total 25170 (delta 645), reused 719
+
-   (delta 538), pack-reused 24219 Receiving objects: 100% (25170/25170),
+      $ cd ~/poky
-   41.02 MiB \| 1.64 MiB/s, done. Resolving deltas: 100% (13385/13385),
+      $ git clone https://github.com/kraj/meta-altera.git
-   done. Checking connectivity... done. The hardware layer now exists
+      Cloning into 'meta-altera'...
+      remote: Counting objects: 25170, done.
+      remote: Compressing objects: 100% (350/350), done.
+      remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
+      Receiving objects: 100% (25170/25170), 41.02 MiB \| 1.64 MiB/s, done.
+      Resolving deltas: 100% (13385/13385), done.
+      Checking connectivity... done.
+
+   The hardware layer now exists
    with other layers inside the Poky reference repository on your build
    host as ``meta-altera`` and contains all the metadata needed to
    support hardware from Altera, which is owned by Intel.
 
-3. *Change the Configuration to Build for a Specific Machine:* The
+#. **Change the Configuration to Build for a Specific Machine:** The
    :term:`MACHINE` variable in the
    ``local.conf`` file specifies the machine for the build. For this
    example, set the ``MACHINE`` variable to "cyclone5". These
@@ -264,25 +317,30 @@ Follow these steps to add a hardware layer:
 
    .. note::
 
-      See the "
+      See the "Examine Your Local Configuration File" step earlier for more
-      Examine Your Local Configuration File
+      information on configuring the build.
-      " step earlier for more information on configuring the build.
 
-4. *Add Your Layer to the Layer Configuration File:* Before you can use
+#. **Add Your Layer to the Layer Configuration File:** Before you can use
    a layer during a build, you must add it to your ``bblayers.conf``
    file, which is found in the
    :term:`Build Directory` ``conf``
    directory.
 
    Use the ``bitbake-layers add-layer`` command to add the layer to the
-   configuration file: $ cd ~/poky/build $ bitbake-layers add-layer
+   configuration file:
-   ../meta-altera NOTE: Starting bitbake server... Parsing recipes: 100%
+
-   \|##################################################################\|
+   .. code-block:: shell
-   Time: 0:00:32 Parsing of 918 .bb files complete (0 cached, 918
+
-   parsed). 1401 targets, 123 skipped, 0 masked, 0 errors. You can find
+      $ cd ~/poky/build
-   more information on adding layers in the "`Adding a Layer Using the
+      $ bitbake-layers add-layer ../meta-altera
-   ``bitbake-layers``
+      NOTE: Starting bitbake server...
-   Script <&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script>`__"
+      Parsing recipes: 100% \|##################################################################\| Time: 0:00:32
+      Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets,
+      123 skipped, 0 masked, 0 errors.
+
+   You can find
+   more information on adding layers in the
+   :ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`
    section.
 
 Completing these steps has added the ``meta-altera`` layer to your Yocto
@@ -293,9 +351,7 @@ Project development environment and configured it to build for the
 
    The previous steps are for demonstration purposes only. If you were
    to attempt to build an image for the "cyclone5" build, you should
-   read the Altera
+   read the Altera README.
-   README
-   .
 
 Creating Your Own General Layer
 ===============================
@@ -308,12 +364,18 @@ configuration file, a ``recipes-example`` subdirectory that contains an
 ``example.bb`` recipe, a licensing file, and a ``README``.
 
 The following commands run the tool to create a layer named
-``meta-mylayer`` in the ``poky`` directory: $ cd ~/poky $ bitbake-layers
+``meta-mylayer`` in the ``poky`` directory:
-create-layer meta-mylayer NOTE: Starting bitbake server... Add your new
+
-layer with 'bitbake-layers add-layer meta-mylayer' For more information
+.. code-block:: shell
-on layers and how to create them, see the "`Creating a General Layer
+
-Using the ``bitbake-layers``
+   $ cd ~/poky
-Script <&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script>`__"
+   $ bitbake-layers create-layer meta-mylayer
+   NOTE: Starting bitbake server...
+   Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+
+For more information
+on layers and how to create them, see the
+:ref:`dev-manual/dev-manual-common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`
 section in the Yocto Project Development Tasks Manual.
 
 Where To Go Next
@@ -323,39 +385,38 @@ Now that you have experienced using the Yocto Project, you might be
 asking yourself "What now?" The Yocto Project has many sources of
 information including the website, wiki pages, and user manuals:
 
--  *Website:* The :yocto_home:`Yocto Project Website <>` provides
+-  **Website:** The :yocto_home:`Yocto Project Website <>` provides
    background information, the latest builds, breaking news, full
    development documentation, and access to a rich Yocto Project
    Development Community into which you can tap.
 
--  *Developer Screencast:* The `Getting Started with the Yocto Project -
+-  **Developer Screencast:** The `Getting Started with the Yocto Project -
    New Developer Screencast Tutorial <http://vimeo.com/36450321>`__
    provides a 30-minute video created for users unfamiliar with the
    Yocto Project but familiar with Linux build hosts. While this
    screencast is somewhat dated, the introductory and fundamental
    concepts are useful for the beginner.
 
--  *Yocto Project Overview and Concepts Manual:* The `Yocto Project
+-  **Yocto Project Overview and Concepts Manual:** The
-   Overview and Concepts Manual <&YOCTO_DOCS_OM_URL;>`__ is a great
+   :doc:`../overview-manual/overview-manual` is a great
    place to start to learn about the Yocto Project. This manual
    introduces you to the Yocto Project and its development environment.
    The manual also provides conceptual information for various aspects
    of the Yocto Project.
 
--  *Yocto Project Wiki:* The :yocto_wiki:`Yocto Project Wiki <>`
+-  **Yocto Project Wiki:** The :yocto_wiki:`Yocto Project Wiki <>`
    provides additional information on where to go next when ramping up
    with the Yocto Project, release information, project planning, and QA
    information.
 
--  *Yocto Project Mailing Lists:* Related mailing lists provide a forum
+-  **Yocto Project Mailing Lists:** Related mailing lists provide a forum
    for discussion, patch submission and announcements. Several mailing
    lists exist and are grouped according to areas of concern. See the
-   "`Mailing lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__"
+   :ref:`ref-manual/resources:mailing lists`
    section in the Yocto Project Reference Manual for a complete list of
    Yocto Project mailing lists.
 
--  *Comprehensive List of Links and Other Documentation:* The "`Links
+-  **Comprehensive List of Links and Other Documentation:** The
-   and Related
+   :ref:`ref-manual/resources:links and related documentation`
-   Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__"
    section in the Yocto Project Reference Manual provides a
    comprehensive list of all related links and other user documentation.