sphinx: overview-manual: Various URL, code block and other fixes to imported data

(From yocto-docs rev: 3325fe660dfea24fba2f964a0060664e3c67459a)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

4 files changed, 270 insertions, 236 deletions

diff --git a/documentation/overview-manual/overview-manual-concepts.rst b/documentation/overview-manual/overview-manual-concepts.rst
index 7f8f735b37..695984ff1e 100644
--- a/documentation/overview-manual/overview-manual-concepts.rst
+++ b/documentation/overview-manual/overview-manual-concepts.rst
@@ -34,14 +34,14 @@ itself is of various types:
 
 BitBake knows how to combine multiple data sources together and refers
 to each data source as a layer. For information on layers, see the
-"`Understanding and Creating
-Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
 section of the Yocto Project Development Tasks Manual.
 
 Following are some brief details on these core components. For
 additional information on how these components interact during a build,
-see the "`OpenEmbedded Build System
-Concepts <#openembedded-build-system-build-concepts>`__" section.
+see the
+":ref:`overview-manual/overview-manual-concepts:openembedded build system concepts`"
+section.
 
 .. _usingpoky-components-bitbake:
 
@@ -57,14 +57,23 @@ This section briefly introduces BitBake. If you want more information on
 BitBake, see the :doc:`BitBake User Manual <bitbake:index>`.
 
 To see a list of the options BitBake supports, use either of the
-following commands: $ bitbake -h $ bitbake --help
+following commands:
+::
+
+   $ bitbake -h
+   $ bitbake --help
 
 The most common usage for BitBake is ``bitbake packagename``, where
 ``packagename`` is the name of the package you want to build (referred
 to as the "target"). The target often equates to the first part of a
 recipe's filename (e.g. "foo" for a recipe named ``foo_1.3.0-r0.bb``).
 So, to process the ``matchbox-desktop_1.2.3.bb`` recipe file, you might
-type the following: $ bitbake matchbox-desktop Several different
+type the following:
+::
+
+   $ bitbake matchbox-desktop
+
+Several different
 versions of ``matchbox-desktop`` might exist. BitBake chooses the one
 selected by the distribution configuration. You can get more details
 about how BitBake chooses between different target versions and
@@ -153,9 +162,8 @@ By convention, layers in the Yocto Project follow a specific form.
 Conforming to a known structure allows BitBake to make assumptions
 during builds on where to find types of metadata. You can find
 procedures and learn about tools (i.e. ``bitbake-layers``) for creating
-layers suitable for the Yocto Project in the "`Understanding and
-Creating
-Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
+layers suitable for the Yocto Project in the
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
 section of the Yocto Project Development Tasks Manual.
 
 .. _openembedded-build-system-build-concepts:
@@ -225,7 +233,7 @@ reside as example files in the ``build/conf`` directory of the
 :term:`Source Directory`. For simplicity,
 this section refers to the Source Directory as the "Poky Directory."
 
-When you clone the `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository
+When you clone the :term:`Poky` Git repository
 or you download and unpack a Yocto Project release, you can set up the
 Source Directory to be named anything you want. For this discussion, the
 cloned repository uses the default name ``poky``.
@@ -238,7 +246,7 @@ cloned repository uses the default name ``poky``.
 The ``meta-poky`` layer inside Poky contains a ``conf`` directory that
 has example configuration files. These example files are used as a basis
 for creating actual configuration files when you source
-````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, which is the
+:ref:`structure-core-script`, which is the
 build environment script.
 
 Sourcing the build environment script creates a
@@ -251,8 +259,8 @@ if versions do not already exist in the Build Directory at the time you
 source the build environment setup script.
 
 Because the Poky repository is fundamentally an aggregation of existing
-repositories, some users might be familiar with running the ```` script
-in the context of separate
+repositories, some users might be familiar with running the
+:ref:`structure-core-script` script in the context of separate
 :term:`OpenEmbedded-Core (OE-Core)` and BitBake
 repositories rather than a single Poky repository. This discussion
 assumes the script is executed from within a cloned or unpacked version
@@ -320,16 +328,16 @@ The ``bblayers.conf`` file tells BitBake what layers you want considered
 during the build. By default, the layers listed in this file include
 layers minimally needed by the build system. However, you must manually
 add any custom layers you have created. You can find more information on
-working with the ``bblayers.conf`` file in the "`Enabling Your
-Layer <&YOCTO_DOCS_DEV_URL;#enabling-your-layer>`__" section in the
-Yocto Project Development Tasks Manual.
+working with the ``bblayers.conf`` file in the
+":ref:`dev-manual/dev-manual-common-tasks:enabling your layer`"
+section in the Yocto Project Development Tasks Manual.
 
 The files ``site.conf`` and ``auto.conf`` are not created by the
 environment initialization script. If you want the ``site.conf`` file,
 you need to create that yourself. The ``auto.conf`` file is typically
 created by an autobuilder:
 
--  *``site.conf``:* You can use the ``conf/site.conf`` configuration
+-  *site.conf:* You can use the ``conf/site.conf`` configuration
    file to configure multiple build directories. For example, suppose
    you had several build environments and they shared some common
    features. You can set these default build properties here. A good
@@ -346,7 +354,7 @@ created by an autobuilder:
    configurations within that build directory's ``conf/local.conf``
    file.
 
--  *``auto.conf``:* The file is usually created and written to by an
+-  *auto.conf:* The file is usually created and written to by an
    autobuilder. The settings put into the file are typically the same as
    you would find in the ``conf/local.conf`` or the ``conf/site.conf``
    files.
@@ -382,10 +390,10 @@ In general, three types of layer input exists. You can see them below
 the "User Configuration" box in the `general workflow
 figure <#general-workflow-figure>`__:
 
--  *Metadata (``.bb`` + Patches):* Software layers containing
+-  *Metadata (.bb + Patches):* Software layers containing
    user-supplied recipe files, patches, and append files. A good example
    of a software layer might be the
-   ```meta-qt5`https://github.com/meta-qt5/meta-qt5 layer from
+   `meta-qt5 layer <https://github.com/meta-qt5/meta-qt5>`__ from
    the `OpenEmbedded Layer
    Index <http://layers.openembedded.org/layerindex/branch/master/layers/>`__.
    This layer is for version 5.0 of the popular
@@ -421,8 +429,9 @@ licensing file (e.g. ``COPYING.MIT``) if the layer is to be distributed,
 a ``README`` file as good practice and especially if the layer is to be
 distributed, a configuration directory, and recipe directories. You can
 learn about the general structure for layers used with the Yocto Project
-in the "`Creating Your Own
-Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in the
+in the
+":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`"
+section in the
 Yocto Project Development Tasks Manual. For a general discussion on
 layers and the many layers from which you can draw, see the
 "`Layers <#overview-layers>`__" and "`The Yocto Project Layer
@@ -485,8 +494,7 @@ The BSP Layer provides machine configurations that target specific
 hardware. Everything in this layer is specific to the machine for which
 you are building the image or the SDK. A common structure or form is
 defined for BSP layers. You can learn more about this structure in the
-`Yocto Project Board Support Package (BSP) Developer's
-Guide <&YOCTO_DOCS_BSP_URL;>`__.
+:doc:`../bsp-guide/bsp-guide`.
 
 .. note::
 
@@ -704,8 +712,8 @@ architecture are placed in ``build/tmp/deploy/ipk/qemux86``.
 
 .. _bitbake-dev-environment:
 
-BitBake
--------
+BitBake Tool
+------------
 
 The OpenEmbedded build system uses
 :term:`BitBake` to produce images and
@@ -751,8 +759,7 @@ the source files and unpack them into the
 
 By default, everything is accomplished in the Build Directory, which has
 a defined structure. For additional general information on the Build
-Directory, see the
-"```build/`` <&YOCTO_DOCS_REF_URL;#structure-core-build>`__" section in
+Directory, see the ":ref:`structure-core-build`" section in
 the Yocto Project Reference Manual.
 
 Each recipe has an area in the Build Directory where the unpacked source
@@ -769,8 +776,7 @@ Build Directory's hierarchy:
 -  :term:`PACKAGE_ARCH`: The
    architecture of the built package or packages. Depending on the
    eventual destination of the package or packages (i.e. machine
-   architecture, `build
-   host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, SDK, or
+   architecture, :term:`Build Host`, SDK, or
    specific machine), ``PACKAGE_ARCH`` varies. See the variable's
    description for details.
 
@@ -846,15 +852,14 @@ source files, which are located in the
 For more information on how the source directories are created, see the
 "`Source Fetching <#source-fetching-dev-environment>`__" section. For
 more information on how to create patches and how the build system
-processes patches, see the "`Patching
-Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the
-Yocto Project Development Tasks Manual. You can also see the "`Use
-``devtool modify`` to Modify the Source of an Existing
-Component <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component>`__"
+processes patches, see the
+":ref:`dev-manual/dev-manual-common-tasks:patching code`"
+section in the
+Yocto Project Development Tasks Manual. You can also see the
+":ref:`sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component`"
 section in the Yocto Project Application Development and the Extensible
-Software Development Kit (SDK) manual and the "`Using Traditional Kernel
-Development to Patch the
-Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#using-traditional-kernel-development-to-patch-the-kernel>`__"
+Software Development Kit (SDK) manual and the
+":ref:`kernel-dev/kernel-dev-common:using traditional kernel development to patch the kernel`"
 section in the Yocto Project Linux Kernel Development Manual.
 
 .. _configuration-compilation-and-staging-dev-environment:
@@ -882,7 +887,7 @@ This step in the build process consists of the following tasks:
    depends. A sysroot exists for both the target and for the native
    binaries, which run on the host system.
 
--  *``do_configure``*: This task configures the source by enabling and
+-  *do_configure*: This task configures the source by enabling and
    disabling any build-time and configuration options for the software
    being built. Configurations can come from the recipe itself as well
    as from an inherited class. Additionally, the software itself might
@@ -903,7 +908,7 @@ This step in the build process consists of the following tasks:
    :ref:`autotools <ref-classes-autotools>` class
    :yocto_git:`here </cgit/cgit.cgi/poky/tree/meta/classes/autotools.bbclass>`.
 
--  *``do_compile``*: Once a configuration task has been satisfied,
+-  *do_compile*: Once a configuration task has been satisfied,
    BitBake compiles the source using the
    :ref:`ref-tasks-compile` task.
    Compilation occurs in the directory pointed to by the
@@ -911,7 +916,7 @@ This step in the build process consists of the following tasks:
    ``B`` directory is, by default, the same as the
    :term:`S` directory.
 
--  *``do_install``*: After compilation completes, BitBake executes the
+-  *do_install*: After compilation completes, BitBake executes the
    :ref:`ref-tasks-install` task.
    This task copies files from the ``B`` directory and places them in a
    holding area pointed to by the :term:`D`
@@ -1055,8 +1060,8 @@ data files are deleted from the root filesystem. As part of the final
 stage of package installation, post installation scripts that are part
 of the packages are run. Any scripts that fail to run on the build host
 are run on the target when the target system is first booted. If you are
-using a `read-only root
-filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__,
+using a 
+:ref:`read-only root filesystem <dev-manual/dev-manual-common-tasks:creating a read-only root filesystem>`,
 all the post installation scripts must succeed on the build host during
 the package installation phase since the root filesystem on the target
 is read-only.
@@ -1097,9 +1102,17 @@ the image. The formats used for the root filesystem depend on the
 support compression.
 
 As an example, a dynamically created task when creating a particular
-image type would take the following form: do_image_type So, if the type
+image type would take the following form:
+::
+
+   do_image_type
+
+So, if the type
 as specified by the ``IMAGE_FSTYPES`` were ``ext4``, the dynamically
-generated task would be as follows: do_image_ext4
+generated task would be as follows:
+::
+
+   do_image_ext4
 
 The final task involved in image creation is the
 :ref:`do_image_complete <ref-tasks-image-complete>`
@@ -1217,8 +1230,7 @@ varflag. If some other task depends on such a task, then that task will
 also always be considered out of date, which might not be what you want.
 
 For details on how to view information about a task's signature, see the
-"`Viewing Task Variable
-Dependencies <&YOCTO_DOCS_DEV_URL;#dev-viewing-task-variable-dependencies>`__"
+":ref:`dev-manual/dev-manual-common-tasks:viewing task variable dependencies`"
 section in the Yocto Project Development Tasks Manual.
 
 Setscene Tasks and Shared State
@@ -1397,8 +1409,7 @@ can initialize the environment before using the tools.
       section.
 
    -  For information on setting up a cross-development environment, see
-      the `Yocto Project Application Development and the Extensible
-      Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
+      the :doc:`../sdk-manual/sdk-manual` manual.
 
 All the output files for an SDK are written to the ``deploy/sdk`` folder
 inside the :term:`Build Directory` as
@@ -1475,13 +1486,10 @@ Cross-Development Toolchain Generation
 ======================================
 
 The Yocto Project does most of the work for you when it comes to
-creating `cross-development
-toolchains <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__. This
+creating :ref:`sdk-manual/sdk-intro:the cross-development toolchain`. This
 section provides some technical background on how cross-development
 toolchains are created and used. For more information on toolchains, you
-can also see the `Yocto Project Application Development and the
-Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__
-manual.
+can also see the :doc:`../sdk-manual/sdk-manual` manual.
 
 In the Yocto Project development environment, cross-development
 toolchains are used to build images and applications that run on the
@@ -1514,8 +1522,10 @@ cross-compiler that is used internally within BitBake only.
    .
 
 The chain of events that occurs when ``gcc-cross`` is bootstrapped is as
-follows: gcc -> binutils-cross -> gcc-cross-initial ->
-linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
+follows:
+::
+
+   gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime
 
 -  ``gcc``: The build host's GNU Compiler Collection (GCC).
 
@@ -1571,9 +1581,10 @@ might not be the same machine as the Build Host.
    can take advantage of pre-built images that ship with the Yocto
    Project and already contain cross-development toolchain installers.
 
-Here is the bootstrap process for the relocatable toolchain: gcc ->
-binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers ->
-glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
+Here is the bootstrap process for the relocatable toolchain:
+::
+
+   gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian
 
 -  ``gcc``: The build host's GNU Compiler Collection (GCC).
 
@@ -1668,18 +1679,15 @@ them if they are deemed to be valid.
       the shared state packages. Consequently, considerations exist that
       affect maintaining shared state feeds. For information on how the
       build system works with packages and can track incrementing ``PR``
-      information, see the "`Automatically Incrementing a Binary Package
-      Revision
-      Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__"
+      information, see the ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`"
       section in the Yocto Project Development Tasks Manual.
 
    -  The code in the build system that supports incremental builds is
       not simple code. For techniques that help you work around issues
-      related to shared state code, see the "`Viewing Metadata Used to
-      Create the Input Signature of a Shared State
-      Task <&YOCTO_DOCS_DEV_URL;#dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task>`__"
-      and "`Invalidating Shared State to Force a Task to
-      Run <&YOCTO_DOCS_DEV_URL;#dev-invalidating-shared-state-to-force-a-task-to-run>`__"
+      related to shared state code, see the
+      ":ref:`dev-manual/dev-manual-common-tasks:viewing metadata used to create the input signature of a shared state task`"
+      and
+      ":ref:`dev-manual/dev-manual-common-tasks:invalidating shared state to force a task to run`"
       sections both in the Yocto Project Development Tasks Manual.
 
 The rest of this section goes into detail about the overall incremental
@@ -1754,15 +1762,22 @@ to the task.
 Like the ``WORKDIR`` case, situations exist where dependencies should be
 ignored. For these situations, you can instruct the build process to
 ignore a dependency by using a line like the following:
-PACKAGE_ARCHS[vardepsexclude] = "MACHINE" This example ensures that the
-:term:`PACKAGE_ARCHS` variable
-does not depend on the value of
-:term:`MACHINE`, even if it does
+::
+
+   PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
+
+This example ensures that the :term:`PACKAGE_ARCHS` variable
+does not depend on the value of :term:`MACHINE`, even if it does
 reference it.
 
 Equally, there are cases where you need to add dependencies BitBake is
 not able to find. You can accomplish this by using a line like the
-following: PACKAGE_ARCHS[vardeps] = "MACHINE" This example explicitly
+following:
+::
+
+   PACKAGE_ARCHS[vardeps] = "MACHINE"
+
+This example explicitly
 adds the ``MACHINE`` variable as a dependency for ``PACKAGE_ARCHS``.
 
 As an example, consider a case with in-line Python where BitBake is not
@@ -1788,12 +1803,16 @@ and the dependent task hashes can be influenced. Within the BitBake
 configuration file, you can give BitBake some extra information to help
 it construct the basehash. The following statement effectively results
 in a list of global variable dependency excludes (i.e. variables never
-included in any checksum): BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH
-PWD BB_TASKHASH BBPATH DL_DIR \\ SSTATE_DIR THISDIR FILESEXTRAPATHS
-FILE_DIRNAME HOME LOGNAME SHELL TERM \\ USER FILESPATH STAGING_DIR_HOST
-STAGING_DIR_TARGET COREBASE PRSERV_HOST \\ PRSERV_DUMPDIR
-PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\ CCACHE_DIR
-EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" The
+included in any checksum):
+::
+
+   BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\
+       SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\
+       USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \\
+       PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \\
+       CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
+
+The
 previous example excludes
 :term:`WORKDIR` since that variable
 is actually constructed as a path within
@@ -1810,8 +1829,12 @@ desired. This file defines the two basic signature generators
 "OEBasicHash". By default, a dummy "noop" signature handler is enabled
 in BitBake. This means that behavior is unchanged from previous
 versions. OE-Core uses the "OEBasicHash" signature handler by default
-through this setting in the ``bitbake.conf`` file: BB_SIGNATURE_HANDLER
-?= "OEBasicHash" The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same
+through this setting in the ``bitbake.conf`` file:
+::
+
+   BB_SIGNATURE_HANDLER ?= "OEBasicHash"
+
+The "OEBasicHash" ``BB_SIGNATURE_HANDLER`` is the same
 as the "OEBasic" version but adds the task hash to the `stamp
 files <#stamp-files-and-the-rerunning-of-tasks>`__. This results in any
 metadata change that changes the task hash, automatically causing the
@@ -1862,12 +1885,21 @@ implementation hidden in ``sstate`` class. From a user's perspective,
 adding shared state wrapping to a task is as simple as this
 :ref:`ref-tasks-deploy` example taken
 from the :ref:`deploy <ref-classes-deploy>` class:
-DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy"
-do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
-do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" python
-do_deploy_setscene () { sstate_setscene(d) } addtask do_deploy_setscene
-do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
-"${MACHINE_ARCH}" The following list explains the previous example:
+::
+
+   DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
+   SSTATETASKS += "do_deploy"
+   do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
+   do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
+
+   python do_deploy_setscene () {
+       sstate_setscene(d)
+   }
+   addtask do_deploy_setscene
+   do_deploy[dirs] = "${DEPLOYDIR} ${B}"
+   do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"
+
+The following list explains the previous example:
 
 -  Adding "do_deploy" to ``SSTATETASKS`` adds some required
    sstate-related processing, which is implemented in the
@@ -1907,9 +1939,15 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
       task.
 
 -  The following task definition is glue logic needed to make the
-   previous settings effective: python do_deploy_setscene () {
-   sstate_setscene(d) } addtask do_deploy_setscene ``sstate_setscene()``
-   takes the flags above as input and accelerates the ``do_deploy`` task
+   previous settings effective:
+   ::
+
+      python do_deploy_setscene () {
+          sstate_setscene(d)
+      }
+      addtask do_deploy_setscene
+
+  ``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task
    through the shared state cache if possible. If the task was
    accelerated, ``sstate_setscene()`` returns True. Otherwise, it
    returns False, and the normal ``do_deploy`` task runs. For more
@@ -1941,7 +1979,7 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
       ::
 
               do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
-                                     
+
 
 -  The ``do_deploy[stamp-extra-info] = "${MACHINE_ARCH}"`` line appends
    extra metadata to the `stamp
@@ -1956,20 +1994,27 @@ do_deploy[dirs] = "${DEPLOYDIR} ${B}" do_deploy[stamp-extra-info] =
    ``PKGDESTWORK`` and ``SHLIBWORK`` as shared state input directories,
    which populates the shared state cache, and ``PKGDATA_DIR`` and
    ``SHLIBSDIR`` as the corresponding shared state output directories:
-   do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
-   do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
+   ::
+
+      do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
+      do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
 
 -  These methods also include the ability to take a lockfile when
    manipulating shared state directory structures, for cases where file
-   additions or removals are sensitive: do_package[sstate-lockfile] =
-   "${PACKAGELOCK}"
+   additions or removals are sensitive:
+   ::
+
+      do_package[sstate-lockfile] = "${PACKAGELOCK}"
 
 Behind the scenes, the shared state code works by looking in
 :term:`SSTATE_DIR` and
 :term:`SSTATE_MIRRORS` for
-shared state files. Here is an example: SSTATE_MIRRORS ?= "\\ file://.\*
-http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\
-file://.\* file:///some/local/dir/sstate/PATH"
+shared state files. Here is an example:
+::
+
+   SSTATE_MIRRORS ?= "\
+       file://.\* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
+       file://.\* file:///some/local/dir/sstate/PATH"
 
 .. note::
 
@@ -2164,11 +2209,11 @@ accomplished using fakeroot.
    , giving the following:
    ::
 
-             fakeroot do_mytask () {
-                 ...
-             }
-             do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
-                      
+      fakeroot do_mytask () {
+          ...
+      }
+      do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
+
 
 For more information, see the
 :term:`FAKEROOT* <bitbake:FAKEROOT>` variables in the
diff --git a/documentation/overview-manual/overview-manual-development-environment.rst b/documentation/overview-manual/overview-manual-development-environment.rst
index f89e9b9dd4..273e1027da 100644
--- a/documentation/overview-manual/overview-manual-development-environment.rst
+++ b/documentation/overview-manual/overview-manual-development-environment.rst
@@ -50,8 +50,7 @@ Community
 The Development Host
 ====================
 
-A development host or `build
-host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ is key to
+A development host or :term:`Build Host` is key to
 using the Yocto Project. Because the goal of the Yocto Project is to
 develop images or applications that run on embedded hardware,
 development of those images and applications generally takes place on a
@@ -68,8 +67,9 @@ set it up as the development host by using
 to set up a CROPS machine, you effectively have access to a shell
 environment that is similar to what you see when using a Linux-based
 development host. For the steps needed to set up a system using CROPS,
-see the "`Setting Up to Use CROss PlatformS
-(CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in
+see the
+":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
+section in
 the Yocto Project Development Tasks Manual.
 
 If your development host is going to be a system that runs a Linux
@@ -78,8 +78,8 @@ for use with the Yocto Project. You need to be sure that the Linux
 distribution on the system is one that supports the Yocto Project. You
 also need to be sure that the correct set of host packages are installed
 that allow development using the Yocto Project. For the steps needed to
-set up a development host that runs Linux, see the "`Setting Up a Native
-Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__"
+set up a development host that runs Linux, see the
+":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
 section in the Yocto Project Development Tasks Manual.
 
 Once your development host is set up to use the Yocto Project, several
@@ -95,8 +95,8 @@ methods exist for you to do work in the Yocto Project environment:
    within a shell-based environment using components and tools available
    through your Linux distribution and the Yocto Project.
 
-   For a general flow of the build procedures, see the "`Building a
-   Simple Image <&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image>`__"
+   For a general flow of the build procedures, see the
+   ":ref:`dev-manual/dev-manual-common-tasks:building a simple image`"
    section in the Yocto Project Development Tasks Manual.
 
 -  *Board Support Package (BSP) Development:* Development of BSPs
@@ -105,11 +105,9 @@ methods exist for you to do work in the Yocto Project environment:
    hardware. To development BSPs, you need to take some additional steps
    beyond what was described in setting up a development host.
 
-   The `Yocto Project Board Support Package (BSP) Developer's
-   Guide <&YOCTO_DOCS_BSP_URL;>`__ provides BSP-related development
+   The :doc:`../bsp-guide/bsp-guide` provides BSP-related development
    information. For specifics on development host preparation, see the
-   "`Preparing Your Build Host to Work With BSP
-   Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__"
+   ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
    section in the Yocto Project Board Support Package (BSP) Developer's
    Guide.
 
@@ -118,11 +116,10 @@ methods exist for you to do work in the Yocto Project environment:
    using ``devtool`` makes kernel development quicker by reducing
    iteration cycle times.
 
-   The `Yocto Project Linux Kernel Development
-   Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__ provides kernel-related
+   The :doc:`../kernel-dev/kernel-dev` provides kernel-related
    development information. For specifics on development host
-   preparation, see the "`Preparing the Build Host to Work on the
-   Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__"
+   preparation, see the
+   ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
    section in the Yocto Project Linux Kernel Development Manual.
 
 -  *Using Toaster:* The other Yocto Project development method that
@@ -134,8 +131,8 @@ methods exist for you to do work in the Yocto Project environment:
    multiple remote build servers.
 
    For steps that show you how to set up your development host to use
-   Toaster and on how to use Toaster in general, see the `Toaster User
-   Manual <&YOCTO_DOCS_TOAST_URL;>`__.
+   Toaster and on how to use Toaster in general, see the
+   :doc:`../toaster-manual/toaster-manual`.
 
 .. _yocto-project-repositories:
 
@@ -185,8 +182,7 @@ development:
       :align: center
 
    For steps on how to view and access these upstream Git repositories,
-   see the "`Accessing Source
-   Repositories <&YOCTO_DOCS_DEV_URL;#accessing-source-repositories>`__"
+   see the ":ref:`dev-manual/dev-manual-start:accessing source repositories`"
    Section in the Yocto Project Development Tasks Manual.
 
 -  :yocto_dl:`Index of /releases: <releases>` This is an index
@@ -199,9 +195,8 @@ development:
    .. image:: figures/index-downloads.png
       :align: center
 
-   For steps on how to view and access these files, see the "`Accessing
-   Index of
-   Releases <&YOCTO_DOCS_DEV_URL;#accessing-index-of-releases>`__"
+   For steps on how to view and access these files, see the
+   ":ref:`dev-manual/dev-manual-start:accessing index of releases`"
    section in the Yocto Project Development Tasks Manual.
 
 -  *"DOWNLOADS" page for the* :yocto_home:`Yocto Project Website <>` *:*
@@ -215,8 +210,8 @@ development:
    .. image:: figures/yp-download.png
       :align: center
 
-   For steps on how to use the "DOWNLOADS" page, see the "`Using the
-   Downloads Page <&YOCTO_DOCS_DEV_URL;#using-the-downloads-page>`__"
+   For steps on how to use the "DOWNLOADS" page, see the
+   ":ref:`dev-manual/dev-manual-start:using the downloads page`"
    section in the Yocto Project Development Tasks Manual.
 
 .. _gs-git-workflows-and-the-yocto-project:
@@ -252,9 +247,9 @@ and so forth.
 .. note::
 
    For information on finding out who is responsible for (maintains) a
-   particular area of code in the Yocto Project, see the "
-   Submitting a Change to the Yocto Project
-   " section of the Yocto Project Development Tasks Manual.
+   particular area of code in the Yocto Project, see the
+   ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+   section of the Yocto Project Development Tasks Manual.
 
 The Yocto Project ``poky`` Git repository also has an upstream
 contribution Git repository named ``poky-contrib``. You can see all the
@@ -284,9 +279,9 @@ A somewhat formal method exists by which developers commit changes and
 push them into the "contrib" area and subsequently request that the
 maintainer include them into an upstream branch. This process is called
 “submitting a patch” or "submitting a change." For information on
-submitting patches and changes, see the "`Submitting a Change to the
-Yocto Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section
-in the Yocto Project Development Tasks Manual.
+submitting patches and changes, see the
+":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+section in the Yocto Project Development Tasks Manual.
 
 In summary, a single point of entry exists for changes into a "master"
 or development branch of the Git repository, which is controlled by the
@@ -351,20 +346,18 @@ Book <http://book.git-scm.com>`__.
    release to facilitate this workflow. You can find these scripts in
    the ``scripts`` folder of the
    :term:`Source Directory`. For information
-   on how to use these scripts, see the "`Using Scripts to Push a Change
-   Upstream and Request a
-   Pull <&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream>`__" section in
-   the Yocto Project Development Tasks Manual.
+   on how to use these scripts, see the
+   ":ref:`dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull`"
+   section in the Yocto Project Development Tasks Manual.
 
 -  *Patch Workflow:* This workflow allows you to notify the maintainer
    through an email that you have a change (or patch) you would like
    considered for the "master" branch of the Git repository. To send
    this type of change, you format the patch and then send the email
    using the Git commands ``git format-patch`` and ``git send-email``.
-   For information on how to use these scripts, see the "`Submitting a
-   Change to the Yocto
-   Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section in
-   the Yocto Project Development Tasks Manual.
+   For information on how to use these scripts, see the
+   ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+   section in the Yocto Project Development Tasks Manual.
 
 Git
 ===
@@ -389,8 +382,7 @@ commands.
       page, see http://git-scm.com/download.
 
    -  For information beyond the introductory nature in this section,
-      see the "`Locating Yocto Project Source
-      Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
+      see the ":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
       section in the Yocto Project Development Tasks Manual.
 
 Repositories, Tags, and Branches
@@ -422,14 +414,13 @@ You can create a local copy of any repository by "cloning" it with the
 an identical copy of the repository on your development system. Once you
 have a local copy of a repository, you can take steps to develop
 locally. For examples on how to clone Git repositories, see the
-"`Locating Yocto Project Source
-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.
 
 It is important to understand that Git tracks content change and not
 files. Git uses "branches" to organize different development efforts.
 For example, the ``poky`` repository has several branches that include
-the current "DISTRO_NAME_NO_CAP" branch, the "master" branch, and many
+the current "&DISTRO_NAME_NO_CAP;" branch, the "master" branch, and many
 branches for past Yocto Project releases. You can see all the branches
 by going to https://git.yoctoproject.org/cgit.cgi/poky/ and clicking on the
 ``[...]`` link beneath the "Branch" heading.
@@ -444,17 +435,23 @@ local working area (also called a branch) that tracks a specific
 development branch from the upstream source Git repository. in other
 words, you can define your local Git environment to work on any
 development branch in the repository. To help illustrate, consider the
-following example Git commands: $ cd ~ $ git clone
-git://git.yoctoproject.org/poky $ cd poky $ git checkout -b
-DISTRO_NAME_NO_CAP origin/DISTRO_NAME_NO_CAP In the previous example
+following example Git commands:
+::
+
+   $ cd ~
+   $ git clone git://git.yoctoproject.org/poky
+   $ cd poky
+   $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP;
+
+In the previous example
 after moving to the home directory, the ``git clone`` command creates a
 local copy of the upstream ``poky`` Git repository. By default, Git
 checks out the "master" branch for your work. After changing the working
 directory to the new local repository (i.e. ``poky``), the
 ``git checkout`` command creates and checks out a local branch named
-"DISTRO_NAME_NO_CAP", which tracks the upstream
-"origin/DISTRO_NAME_NO_CAP" branch. Changes you make while in this
-branch would ultimately affect the upstream "DISTRO_NAME_NO_CAP" branch
+"&DISTRO_NAME_NO_CAP;", which tracks the upstream
+"origin/&DISTRO_NAME_NO_CAP;" branch. Changes you make while in this
+branch would ultimately affect the upstream "&DISTRO_NAME_NO_CAP;" branch
 of the ``poky`` repository.
 
 It is important to understand that when you create and checkout a local
@@ -462,7 +459,7 @@ working branch based on a branch name, your local environment matches
 the "tip" of that particular development branch at the time you created
 your local branch, which could be different from the files in the
 "master" branch of the upstream repository. In other words, creating and
-checking out a local branch based on the "DISTRO_NAME_NO_CAP" branch
+checking out a local branch based on the "&DISTRO_NAME_NO_CAP;" branch
 name is not the same as checking out the "master" branch in the
 repository. Keep reading to see how you create a local snapshot of a
 Yocto Project Release.
@@ -476,7 +473,7 @@ beneath the "Tag" heading.
 
 Some key tags for the ``poky`` repository are ``jethro-14.0.3``,
 ``morty-16.0.1``, ``pyro-17.0.0``, and
-``DISTRO_NAME_NO_CAP-POKYVERSION``. These tags represent Yocto Project
+``&DISTRO_NAME_NO_CAP;-&POKYVERSION;``. These tags represent Yocto Project
 releases.
 
 When you create a local copy of the Git repository, you also have access
@@ -485,9 +482,16 @@ create and checkout a local working Git branch based on a tag name. When
 you do this, you get a snapshot of the Git repository that reflects the
 state of the files when the change was made associated with that tag.
 The most common use is to checkout a working branch that matches a
-specific Yocto Project release. Here is an example: $ cd ~ $ git clone
-git://git.yoctoproject.org/poky $ cd poky $ git fetch --tags $ git
-checkout tags/rocko-18.0.0 -b my_rocko-18.0.0 In this example, the name
+specific Yocto Project release. Here is an example:
+::
+
+   $ cd ~
+   $ git clone git://git.yoctoproject.org/poky
+   $ cd poky
+   $ git fetch --tags
+   $ git checkout tags/rocko-18.0.0 -b my_rocko-18.0.0
+
+In this example, the name
 of the top-level directory of your local Yocto Project repository is
 ``poky``. After moving to the ``poky`` directory, the ``git fetch``
 command makes all the upstream tags available locally in your
@@ -518,62 +522,62 @@ list (in most cases) simply shows the base command and omits the many
 arguments it supports. See the Git documentation for complete
 descriptions and strategies on how to use these commands:
 
--  *``git init``:* Initializes an empty Git repository. You cannot use
+-  *git init:* Initializes an empty Git repository. You cannot use
    Git commands unless you have a ``.git`` repository.
 
--  *``git clone``:* Creates a local clone of a Git repository that is on
+-  *git clone:* Creates a local clone of a Git repository that is on
    equal footing with a fellow developer’s Git repository or an upstream
    repository.
 
--  *``git add``:* Locally stages updated file contents to the index that
+-  *git add:* Locally stages updated file contents to the index that
    Git uses to track changes. You must stage all files that have changed
    before you can commit them.
 
--  *``git commit``:* Creates a local "commit" that documents the changes
+-  *git commit:* Creates a local "commit" that documents the changes
    you made. Only changes that have been staged can be committed.
    Commits are used for historical purposes, for determining if a
    maintainer of a project will allow the change, and for ultimately
    pushing the change from your local Git repository into the project’s
    upstream repository.
 
--  *``git status``:* Reports any modified files that possibly need to be
+-  *git status:* Reports any modified files that possibly need to be
    staged and gives you a status of where you stand regarding local
    commits as compared to the upstream repository.
 
--  *``git checkout`` branch-name:* Changes your local working branch and
+-  *git checkout branch-name:* Changes your local working branch and
    in this form assumes the local branch already exists. This command is
    analogous to "cd".
 
--  *``git checkout –b`` working-branch upstream-branch:* Creates and
+-  *git checkout –b working-branch upstream-branch:* Creates and
    checks out a working branch on your local machine. The local branch
    tracks the upstream branch. You can use your local branch to isolate
    your work. It is a good idea to use local branches when adding
    specific features or changes. Using isolated branches facilitates
    easy removal of changes if they do not work out.
 
--  *``git branch``:* Displays the existing local branches associated
+-  *git branch:* Displays the existing local branches associated
    with your local repository. The branch that you have currently
    checked out is noted with an asterisk character.
 
--  *``git branch -D`` branch-name:* Deletes an existing local branch.
+-  *git branch -D branch-name:* Deletes an existing local branch.
    You need to be in a local branch other than the one you are deleting
    in order to delete branch-name.
 
--  *``git pull --rebase``:* Retrieves information from an upstream Git
+-  *git pull --rebase:* Retrieves information from an upstream Git
    repository and places it in your local Git repository. You use this
    command to make sure you are synchronized with the repository from
    which you are basing changes (.e.g. the "master" branch). The
    "--rebase" option ensures that any local commits you have in your
    branch are preserved at the top of your local branch.
 
--  *``git push`` repo-name local-branch\ ``:``\ upstream-branch:* Sends
+-  *git push repo-name local-branch:upstream-branch:* Sends
    all your committed local changes to the upstream Git repository that
    your local repository is tracking (e.g. a contribution repository).
    The maintainer of the project draws from these repositories to merge
    changes (commits) into the appropriate branch of project's upstream
    repository.
 
--  *``git merge``:* Combines or adds changes from one local branch of
+-  *git merge:* Combines or adds changes from one local branch of
    your repository with another branch. When you create a local Git
    repository, the default branch is named "master". A typical workflow
    is to create a temporary branch that is based off "master" that you
@@ -585,12 +589,12 @@ descriptions and strategies on how to use these commands:
    done with working in that isolated branch, you can safely delete the
    isolated branch.
 
--  *``git cherry-pick`` commits:* Choose and apply specific commits from
+-  *git cherry-pick commits:* Choose and apply specific commits from
    one branch into another branch. There are times when you might not be
    able to merge all the changes in one branch with another but need to
    pick out certain ones.
 
--  *``gitk``:* Provides a GUI view of the branches and changes in your
+-  *gitk:* Provides a GUI view of the branches and changes in your
    local Git repository. This command is a good way to graphically see
    where things have diverged in your local repository.
 
@@ -600,11 +604,11 @@ descriptions and strategies on how to use these commands:
       gitk
       package on your development system to use this command.
 
--  *``git log``:* Reports a history of your commits to the repository.
+-  *git log:* Reports a history of your commits to the repository.
    This report lists all commits regardless of whether you have pushed
    them upstream or not.
 
--  *``git diff``:* Displays line-by-line differences between a local
+-  *git diff:* Displays line-by-line differences between a local
    working file and the same file as understood by Git. This command is
    useful to see what you have changed in any given file.
 
@@ -663,7 +667,6 @@ Project uses in the ``meta/files/common-licenses`` directory in your
 
 For information that can help you maintain compliance with various open
 source licensing during the lifecycle of a product created using the
-Yocto Project, see the "`Maintaining Open Source License Compliance
-During Your Product's
-Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
+Yocto Project, see the
+":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
 section in the Yocto Project Development Tasks Manual.
diff --git a/documentation/overview-manual/overview-manual-intro.rst b/documentation/overview-manual/overview-manual-intro.rst
index 2e96f1e338..3f206fd54b 100644
--- a/documentation/overview-manual/overview-manual-intro.rst
+++ b/documentation/overview-manual/overview-manual-intro.rst
@@ -20,7 +20,7 @@ The following list describes what you can get from this manual:
    provides an introduction to the Yocto Project. You will learn about
    features and challenges of the Yocto Project, the layer model,
    components and tools, development methods, the
-   `Poky <&YOCTO_DOCS_REF_URL;#poky>`__ reference distribution, the
+   :term:`Poky` reference distribution, the
    OpenEmbedded build system workflow, and some basic Yocto terms.
 
 -  `The Yocto Project Development
@@ -30,7 +30,7 @@ The following list describes what you can get from this manual:
    Yocto Project source repositories, workflows using Git and the Yocto
    Project, a Git primer, and information about licensing.
 
--  `Yocto Project Concepts <#overview-manual-concepts>`__\ *:* This
+-  :doc:`overview-manual-concepts` *:* This
    chapter presents various concepts regarding the Yocto Project. You
    can find conceptual information about components, development,
    cross-toolchains, and so forth.
@@ -39,19 +39,17 @@ This manual does not give you the following:
 
 -  *Step-by-step Instructions for Development Tasks:* Instructional
    procedures reside in other manuals within the Yocto Project
-   documentation set. For example, the `Yocto Project Development Tasks
-   Manual <&YOCTO_DOCS_DEV_URL;>`__ provides examples on how to perform
-   various development tasks. As another example, the `Yocto Project
-   Application Development and the Extensible Software Development Kit
-   (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed
+   documentation set. For example, the :doc:`../dev-manual/dev-manual`
+   provides examples on how to perform
+   various development tasks. As another example, the 
+   :doc:`../sdk-manual/sdk-manual` manual contains detailed
    instructions on how to install an SDK, which is used to develop
    applications for target hardware.
 
 -  *Reference Material:* This type of material resides in an appropriate
    reference manual. For example, system variables are documented in the
-   `Yocto Project Reference Manual <&YOCTO_DOCS_REF_URL;>`__. As another
-   example, the `Yocto Project Board Support Package (BSP) Developer's
-   Guide <&YOCTO_DOCS_BSP_URL;>`__ contains reference information on
+   :doc:`../ref-manual/ref-manual`. As another
+   example, the :doc:`../bsp-guide/bsp-guide` contains reference information on
    BSPs.
 
 -  *Detailed Public Information Not Specific to the Yocto Project:* For
@@ -69,8 +67,8 @@ supplemental information is recommended for full comprehension. For
 additional introductory information on the Yocto Project, see the
 :yocto_home:`Yocto Project Website <>`. If you want to build an image
 with no knowledge of Yocto Project as a way of quickly testing it out,
-see the `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document.
+see the :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document.
 For a comprehensive list of links and other documentation, see the
-"`Links and Related
-Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__"
+":ref:`Links and Related
+Documentation <resources-links-and-related-documentation>`"
 section in the Yocto Project Reference Manual.
diff --git a/documentation/overview-manual/overview-manual-yp-intro.rst b/documentation/overview-manual/overview-manual-yp-intro.rst
index 1a71308fc0..13ff7e9f0e 100644
--- a/documentation/overview-manual/overview-manual-yp-intro.rst
+++ b/documentation/overview-manual/overview-manual-yp-intro.rst
@@ -113,7 +113,7 @@ Project:
    development.
 
 -  *Releases According to a Strict Schedule:* Major releases occur on a
-   `six-month cycle <&YOCTO_DOCS_REF_URL;#ref-release-process>`__
+   :doc:`six-month cycle <../ref-manual/ref-release-process>`
    predictably in October and April. The most recent two releases
    support point releases to address common vulnerabilities and
    exposures. This predictability is crucial for projects based on the
@@ -131,8 +131,8 @@ Project:
    in what order to support dependencies, other build systems can
    arbitrarily include packages.
 
--  *License Manifest:* The Yocto Project provides a `license
-   manifest <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__
+-  *License Manifest:* The Yocto Project provides a :ref:`license
+   manifest <dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle>`
    for review by people who need to track the use of open source
    licenses (e.g.legal teams).
 
@@ -154,10 +154,8 @@ developing using the Yocto Project:
    changes need to be made for your particular design can require a
    significant amount of research and investigation. For information
    that helps you transition from trying out the Yocto Project to using
-   it for your project, see the "`What I wish I'd
-   Known <&YOCTO_DOCS_URL;/what-i-wish-id-known/>`__" and
-   "`Transitioning to a Custom Environment for Systems
-   Development <&YOCTO_DOCS_URL;/transitioning-to-a-custom-environment/>`__"
+   it for your project, see the ":ref:`what-i-wish-id-known:what i wish i'd known about yocto project`" and
+   ":ref:`transitioning-to-a-custom-environment:transitioning to a custom environment for systems development`"
    documents on the Yocto Project website.
 
 -  *Project Workflow Could Be Confusing:* The `Yocto Project
@@ -233,8 +231,8 @@ your Metadata, the easier it is to cope with future changes.
       validated.
 
    -  Layers support the inclusion of technologies, hardware components,
-      and software components. The `Yocto Project
-      Compatible <&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project>`__
+      and software components. The :ref:`Yocto Project
+      Compatible <dev-manual/dev-manual-common-tasks:making sure your layer is compatible with yocto project>`
       designation provides a minimum level of standardization that
       contributes to a strong ecosystem. "YP Compatible" is applied to
       appropriate products and software components such as BSPs, other
@@ -280,9 +278,8 @@ view <https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/>`__ of the
 ``meta-yocto-bsp``. Each of these repositories represents a distinct
 layer.
 
-For procedures on how to create layers, see the "`Understanding and
-Creating
-Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
+For procedures on how to create layers, see the 
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
 section in the Yocto Project Development Tasks Manual.
 
 Components and Tools
@@ -292,7 +289,7 @@ The Yocto Project employs a collection of components and tools used by
 the project itself, by project developers, and by those using the Yocto
 Project. These components and tools are open source projects and
 metadata that are separate from the reference distribution
-(`Poky <&YOCTO_DOCS_REF_URL;#poky>`__) and the 
+(:term:`Poky`) and the 
 :term:`OpenEmbedded Build System`. Most of the
 components and tools are downloaded separately.
 
@@ -336,8 +333,8 @@ applications using the Yocto Project:
 
    You can read about the ``devtool`` workflow in the Yocto Project
    Application Development and Extensible Software Development Kit
-   (eSDK) Manual in the "`Using ``devtool`` in Your SDK
-   Workflow' <&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow>`__"
+   (eSDK) Manual in the 
+   ":ref:`sdk-manual/sdk-extensible:using \`\`devtool\`\` in your sdk workflow`"
    section.
 
 -  *Extensible Software Development Kit (eSDK):* The eSDK provides a
@@ -349,14 +346,12 @@ applications using the Yocto Project:
    experience supplemented with the powerful set of ``devtool`` commands
    tailored for the Yocto Project environment.
 
-   For information on the eSDK, see the `Yocto Project Application
-   Development and the Extensible Software Development Kit
-   (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ Manual.
+   For information on the eSDK, see the :doc:`../sdk-manual/sdk-manual` Manual.
 
 -  *Toaster:* Toaster is a web interface to the Yocto Project
    OpenEmbedded build system. Toaster allows you to configure, run, and
    view information about builds. For information on Toaster, see the
-   `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__.
+   :doc:`../toaster-manual/toaster-manual`.
 
 .. _gs-production-tools:
 
@@ -406,7 +401,7 @@ activities using the Yocto Project:
    benefit of the development community.
 
    You can learn more about the AutoBuilder used by the Yocto Project
-   `here <&YOCTO_AB_URL;>`__.
+   Autobuilder :doc:`here <../test-manual/test-manual-understand-autobuilder>`.
 
 -  *Cross-Prelink:* Prelinking is the process of pre-computing the load
    addresses and link tables generated by the dynamic linker as compared
@@ -595,8 +590,8 @@ Linux.
 Development Methods
 ===================
 
-The Yocto Project development environment usually involves a `Build
-Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ and target
+The Yocto Project development environment usually involves a 
+:term:`Build Host` and target
 hardware. You use the Build Host to build images and develop
 applications, while you use the target hardware to test deployed
 software.
@@ -622,8 +617,8 @@ Project.
    supported Linux distribution.
 
    For information on how to set up a Build Host on a system running
-   Linux as its native operating system, see the "`Setting Up a Native
-   Linux Host <&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host>`__"
+   Linux as its native operating system, see the 
+   ":ref:`dev-manual/dev-manual-start:setting up a native linux host`"
    section in the Yocto Project Development Tasks Manual.
 
 -  *CROss PlatformS (CROPS):* Typically, you use
@@ -643,9 +638,8 @@ Project.
    system natively running Linux.
 
    For information on how to set up a Build Host with CROPS, see the
-   "`Setting Up to Use CROss PlatformS
-   (CROPS) <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops>`__" section in
-   the Yocto Project Development Tasks Manual.
+   ":ref:`dev-manual/dev-manual-start:setting up to use cross platforms (crops)`"
+   section in the Yocto Project Development Tasks Manual.
 
 -  *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem
    For Linux v2 to set up a build host using Windows 10.
@@ -661,9 +655,8 @@ Project.
    virtualization technology.
 
    For information on how to set up a Build Host with WSLv2, see the
-   "`Setting Up to Use Windows Subsystem For
-   Linux <&YOCTO_DOCS_DEV_URL;#setting-up-to-use-wsl>`__" section in the
-   Yocto Project Development Tasks Manual.
+   ":ref:dev-manual/dev-manual-start:setting up to use windows subsystem for linux (wslv2)`"
+   section in the Yocto Project Development Tasks Manual.
 
 -  *Toaster:* Regardless of what your Build Host is running, you can use
    Toaster to develop software using the Yocto Project. Toaster is a web
@@ -673,8 +666,8 @@ Project.
    builds is collected and stored in a database. You can use Toaster to
    configure and start builds on multiple remote build servers.
 
-   For information about and how to use Toaster, see the `Toaster User
-   Manual <&YOCTO_DOCS_TOAST_URL;>`__.
+   For information about and how to use Toaster, see the 
+   :doc:`../toaster-manual/toaster-manual`.
 
 .. _reference-embedded-distribution:
 
@@ -686,7 +679,7 @@ Project's reference distribution or Reference OS Kit. Poky contains the
 :term:`OpenEmbedded Build System`
 (:term:`BitBake` and
 :term:`OpenEmbedded-Core (OE-Core)`) as well as a set
-of `metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ to get you started
+of :term:`Metadata` to get you started
 building your own distro. In other words, Poky is a base specification
 of the functionality needed for a typical embedded system as well as the
 components from the Yocto Project that allow you to build a distribution
@@ -747,8 +740,7 @@ Poky has a regular, well established, six-month release cycle under its
 own version. Major releases occur at the same time major releases (point
 releases) occur for the Yocto Project, which are typically in the Spring
 and Fall. For more information on the Yocto Project release schedule and
-cadence, see the "`Yocto Project Releases and the Stable Release
-Process <&YOCTO_DOCS_REF_URL;#ref-release-process>`__" chapter in the
+cadence, see the ":doc:`../ref-manual/ref-release-process`" chapter in the
 Yocto Project Reference Manual.
 
 Much has been said about Poky being a "default configuration." A default
@@ -827,8 +819,8 @@ Some Basic Terms
 ================
 
 It helps to understand some basic fundamental terms when learning the
-Yocto Project. Although a list of terms exists in the "`Yocto Project
-Terms <&YOCTO_DOCS_REF_URL;#ref-terms>`__" section of the Yocto Project
+Yocto Project. Although a list of terms exists in the ":doc:`Yocto Project
+Terms <../ref-manual/ref-terms>`" section of the Yocto Project
 Reference Manual, this section provides the definitions of some terms
 helpful for getting started:
 
@@ -842,9 +834,7 @@ helpful for getting started:
    application developers. This eSDK allows developers to incorporate
    their library and programming changes back into the image to make
    their code available to other application developers. For information
-   on the eSDK, see the `Yocto Project Application Development and the
-   Extensible Software Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__
-   manual.
+   on the eSDK, see the :doc:`../sdk-manual/sdk-manual` manual.
 
 -  *Layer:* A collection of related recipes. Layers allow you to
    consolidate related metadata to customize your build. Layers also
@@ -855,12 +845,11 @@ helpful for getting started:
    them. You can search the Layer Index for layers used within Yocto
    Project.
 
-   For more detailed information on layers, see the "`Understanding and
-   Creating
-   Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
+   For more detailed information on layers, see the 
+   ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
    section in the Yocto Project Development Tasks Manual. For a
-   discussion specifically on BSP Layers, see the "`BSP
-   Layers <&YOCTO_DOCS_BSP_URL;#bsp-layers>`__" section in the Yocto
+   discussion specifically on BSP Layers, see the 
+   ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto
    Project Board Support Packages (BSP) Developer's Guide.
 
 -  *Metadata:* A key element of the Yocto Project is the Metadata that
@@ -913,8 +902,7 @@ helpful for getting started:
 
    It is worth noting that the term "package" can, in general, have
    subtle meanings. For example, the packages referred to in the
-   "`Required Packages for the Build
-   Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__"
+   ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
    section in the Yocto Project Reference Manual are compiled binaries
    that, when installed, add functionality to your Linux distribution.