sphinx: initial sphinx support

This commit is autogenerated pandoc to generate an inital set
of reST files based on DocBook XML files.

A .rst file is generated for each .xml files in all manuals with this
command:

cd <manual>
for i in *.xml; do \
  pandoc -f docbook -t rst --shift-heading-level-by=-1 \
  $i -o $(basename $i .xml).rst \
done

The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux).

Also created an initial top level index file for each document, and
added all 'books' to the top leve index.rst file.

The YP manuals layout is organized as:

Book
  Chapter
    Section
      Section
        Section

Sphinx uses section headers to create the document structure.
ReStructuredText defines sections headers like that:

   To break longer text up into sections, you use section headers. These
   are a single line of text (one or more words) with adornment: an
   underline alone, or an underline and an overline together, in dashes
   "-----", equals "======", tildes "~~~~~~" or any of the
   non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel
   comfortable with. An underline-only adornment is distinct from an
   overline-and-underline adornment using the same character. The
   underline/overline must be at least as long as the title text. Be
   consistent, since all sections marked with the same adornment style
   are deemed to be at the same level:

Let's define the following convention when converting from Docbook:

Book                => overline ===   (Title)
  Chapter           => overline ***   (1.)
    Section         => ====           (1.1)
      Section       => ----           (1.1.1)
        Section     => ~~~~           (1.1.1.1)
          Section   => ^^^^           (1.1.1.1.1)

During the conversion with pandoc, we used --shift-heading-level=-1 to
convert most of DocBook headings automatically. However with this
setting, the Chapter header was removed, so I added it back
manually. Without this setting all headings were off by one, which was
more difficult to manually fix.

At least with this change, we now have the same TOC with Sphinx and
DocBook.

(From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8)

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

1 files changed, 369 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-terms.rst b/documentation/ref-manual/ref-terms.rst
new file mode 100644
index 0000000000..16e0aa7568
--- /dev/null
+++ b/documentation/ref-manual/ref-terms.rst
@@ -0,0 +1,369 @@
+*******************
+Yocto Project Terms
+*******************
+
+Following is a list of terms and definitions users new to the Yocto
+Project development environment might find helpful. While some of these
+terms are universal, the list includes them just in case:
+
+-  *Append Files:* Files that append build information to a recipe file.
+   Append files are known as BitBake append files and ``.bbappend``
+   files. The OpenEmbedded build system expects every append file to
+   have a corresponding recipe (``.bb``) file. Furthermore, the append
+   file and corresponding recipe file must use the same root filename.
+   The filenames can differ only in the file type suffix used (e.g.
+   ``formfactor_0.0.bb`` and ``formfactor_0.0.bbappend``).
+
+   Information in append files extends or overrides the information in
+   the similarly-named recipe file. For an example of an append file in
+   use, see the "`Using .bbappend Files in Your
+   Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in the
+   Yocto Project Development Tasks Manual.
+
+   When you name an append file, you can use the "``%``" wildcard
+   character to allow for matching recipe names. For example, suppose
+   you have an append file named as follows: busybox_1.21.%.bbappend
+   That append file would match any ``busybox_1.21.``\ x\ ``.bb``
+   version of the recipe. So, the append file would match any of the
+   following recipe names: busybox_1.21.1.bb busybox_1.21.2.bb
+   busybox_1.21.3.bb busybox_1.21.10.bb busybox_1.21.25.bb
+
+   .. note::
+
+      The use of the "
+      %
+      " character is limited in that it only works directly in front of
+      the
+      .bbappend
+      portion of the append file's name. You cannot use the wildcard
+      character in any other location of the name.
+
+-  *BitBake:* The task executor and scheduler used by the OpenEmbedded
+   build system to build images. For more information on BitBake, see
+   the `BitBake User Manual <&YOCTO_DOCS_BB_URL;>`__.
+
+-  *Board Support Package (BSP):* A group of drivers, definitions, and
+   other components that provide support for a specific hardware
+   configuration. For more information on BSPs, see the `Yocto Project
+   Board Support Package (BSP) Developer's
+   Guide <&YOCTO_DOCS_BSP_URL;>`__.
+
+-  *Build Directory:* This term refers to the area used by the
+   OpenEmbedded build system for builds. The area is created when you
+   ``source`` the setup environment script that is found in the Source
+   Directory (i.e. ````` <#structure-core-script>`__). The
+   ```TOPDIR`` <#var-TOPDIR>`__ variable points to the Build Directory.
+
+   You have a lot of flexibility when creating the Build Directory.
+   Following are some examples that show how to create the directory.
+   The examples assume your `Source Directory <#source-directory>`__ is
+   named ``poky``:
+
+   -  Create the Build Directory inside your Source Directory and let
+      the name of the Build Directory default to ``build``: $ cd
+      $HOME/poky $ source OE_INIT_FILE
+
+   -  Create the Build Directory inside your home directory and
+      specifically name it ``test-builds``: $ cd $HOME $ source
+      poky/OE_INIT_FILE test-builds
+
+   -  Provide a directory path and specifically name the Build
+      Directory. Any intermediate folders in the pathname must exist.
+      This next example creates a Build Directory named
+      ``YP-POKYVERSION`` in your home directory within the existing
+      directory ``mybuilds``: $ cd $HOME $ source
+      $HOME/poky/OE_INIT_FILE $HOME/mybuilds/YP-POKYVERSION
+
+   .. note::
+
+      By default, the Build Directory contains
+      TMPDIR
+      , which is a temporary directory the build system uses for its
+      work.
+      TMPDIR
+      cannot be under NFS. Thus, by default, the Build Directory cannot
+      be under NFS. However, if you need the Build Directory to be under
+      NFS, you can set this up by setting
+      TMPDIR
+      in your
+      local.conf
+      file to use a local drive. Doing so effectively separates
+      TMPDIR
+      from
+      TOPDIR
+      , which is the Build Directory.
+
+-  *Build Host:* The system used to build images in a Yocto Project
+   Development environment. The build system is sometimes referred to as
+   the development host.
+
+-  *Classes:* Files that provide for logic encapsulation and inheritance
+   so that commonly used patterns can be defined once and then easily
+   used in multiple recipes. For reference information on the Yocto
+   Project classes, see the "`Classes <#ref-classes>`__" chapter. Class
+   files end with the ``.bbclass`` filename extension.
+
+-  *Configuration File:* Files that hold global definitions of
+   variables, user-defined variables, and hardware configuration
+   information. These files tell the OpenEmbedded build system what to
+   build and what to put into the image to support a particular
+   platform.
+
+   Configuration files end with a ``.conf`` filename extension. The
+   ``conf/local.conf`` configuration file in the `Build
+   Directory <#build-directory>`__ contains user-defined variables that
+   affect every build. The ``meta-poky/conf/distro/poky.conf``
+   configuration file defines Yocto "distro" configuration variables
+   used only when building with this policy. Machine configuration
+   files, which are located throughout the `Source
+   Directory <#source-directory>`__, define variables for specific
+   hardware and are only used when building for that target (e.g. the
+   ``machine/beaglebone.conf`` configuration file defines variables for
+   the Texas Instruments ARM Cortex-A8 development board).
+
+-  *Container Layer:* Layers that hold other layers. An example of a
+   container layer is OpenEmbedded's
+   ```meta-openembedded`` <https://github.com/openembedded/meta-openembedded>`__
+   layer. The ``meta-openembedded`` layer contains many ``meta-*``
+   layers.
+
+-  *Cross-Development Toolchain:* In general, a cross-development
+   toolchain is a collection of software development tools and utilities
+   that run on one architecture and allow you to develop software for a
+   different, or targeted, architecture. These toolchains contain
+   cross-compilers, linkers, and debuggers that are specific to the
+   target architecture.
+
+   The Yocto Project supports two different cross-development
+   toolchains:
+
+   -  A toolchain only used by and within BitBake when building an image
+      for a target architecture.
+
+   -  A relocatable toolchain used outside of BitBake by developers when
+      developing applications that will run on a targeted device.
+
+   Creation of these toolchains is simple and automated. For information
+   on toolchain concepts as they apply to the Yocto Project, see the
+   "`Cross-Development Toolchain
+   Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
+   section in the Yocto Project Overview and Concepts Manual. You can
+   also find more information on using the relocatable toolchain in the
+   `Yocto Project Application Development and the Extensible Software
+   Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
+
+-  *Extensible Software Development Kit (eSDK):* A custom SDK for
+   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.
+
+-  *Image:* An image is an artifact of the BitBake build process given a
+   collection of recipes and related Metadata. Images are the binary
+   output that run on specific hardware or QEMU and are used for
+   specific use-cases. For a list of the supported image types that the
+   Yocto Project provides, see the "`Images <#ref-images>`__" chapter.
+
+-  *Layer:* A collection of related recipes. Layers allow you to
+   consolidate related metadata to customize your build. Layers also
+   isolate information used when building for multiple architectures.
+   Layers are hierarchical in their ability to override previous
+   specifications. You can include any number of available layers from
+   the Yocto Project and customize the build by adding your layers after
+   them. You can search the Layer Index for layers used within Yocto
+   Project.
+
+   For introductory information on layers, see the "`The Yocto Project
+   Layer Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__"
+   section in the Yocto Project Overview and Concepts Manual. For more
+   detailed information on layers, see the "`Understanding and Creating
+   Layers <&YOCTO_DOCS_DEV_URL;#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
+   Project Board Support Packages (BSP) Developer's Guide.
+
+-  *Metadata:* A key element of the Yocto Project is the Metadata that
+   is used to construct a Linux distribution and is contained in the
+   files that the `OpenEmbedded build system <#build-system-term>`__
+   parses when building an image. In general, Metadata includes recipes,
+   configuration files, and other information that refers to the build
+   instructions themselves, as well as the data used to control what
+   things get built and the effects of the build. Metadata also includes
+   commands and data used to indicate what versions of software are
+   used, from where they are obtained, and changes or additions to the
+   software itself (patches or auxiliary files) that are used to fix
+   bugs or customize the software for use in a particular situation.
+   OpenEmbedded-Core is an important set of validated metadata.
+
+   In the context of the kernel ("kernel Metadata"), the term refers to
+   the kernel config fragments and features contained in the
+   ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache>`__
+   Git repository.
+
+-  *OpenEmbedded-Core (OE-Core):* OE-Core is metadata comprised of
+   foundational recipes, classes, and associated files that are meant to
+   be common among many different OpenEmbedded-derived systems,
+   including the Yocto Project. OE-Core is a curated subset of an
+   original repository developed by the OpenEmbedded community that has
+   been pared down into a smaller, core set of continuously validated
+   recipes. The result is a tightly controlled and an quality-assured
+   core set of recipes.
+
+   You can see the Metadata in the ``meta`` directory of the Yocto
+   Project `Source
+   Repositories <http://git.yoctoproject.org/cgit/cgit.cgi>`__.
+
+-  *OpenEmbedded Build System:* The build system specific to the Yocto
+   Project. The OpenEmbedded build system is based on another project
+   known as "Poky", which uses `BitBake <#bitbake-term>`__ as the task
+   executor. Throughout the Yocto Project documentation set, the
+   OpenEmbedded build system is sometimes referred to simply as "the
+   build system". If other build systems, such as a host or target build
+   system are referenced, the documentation clearly states the
+   difference.
+
+   .. note::
+
+      For some historical information about Poky, see the
+      Poky
+      term.
+
+-  *Package:* In the context of the Yocto Project, this term refers to a
+   recipe's packaged output produced by BitBake (i.e. a "baked recipe").
+   A package is generally the compiled binaries produced from the
+   recipe's sources. You "bake" something by running it through BitBake.
+
+   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 <#required-packages-for-the-build-host>`__" section are compiled
+   binaries that, when installed, add functionality to your Linux
+   distribution.
+
+   Another point worth noting is that historically within the Yocto
+   Project, recipes were referred to as packages - thus, the existence
+   of several BitBake variables that are seemingly mis-named, (e.g.
+   ```PR`` <#var-PR>`__, ```PV`` <#var-PV>`__, and
+   ```PE`` <#var-PE>`__).
+
+-  *Package Groups:* Arbitrary groups of software Recipes. You use
+   package groups to hold recipes that, when built, usually accomplish a
+   single task. For example, a package group could contain the recipes
+   for a company’s proprietary or value-add software. Or, the package
+   group could contain the recipes that enable graphics. A package group
+   is really just another recipe. Because package group files are
+   recipes, they end with the ``.bb`` filename extension.
+
+-  *Poky:* Poky, which is pronounced *Pock*-ee, is a reference embedded
+   distribution and a reference test configuration. Poky provides the
+   following:
+
+   -  A base-level functional distro used to illustrate how to customize
+      a distribution.
+
+   -  A means by which to test the Yocto Project components (i.e. Poky
+      is used to validate the Yocto Project).
+
+   -  A vehicle through which you can download the Yocto Project.
+
+   Poky is not a product level distro. Rather, it is a good starting
+   point for customization.
+
+   .. note::
+
+      Poky began as an open-source project initially developed by
+      OpenedHand. OpenedHand developed Poky from the existing
+      OpenEmbedded build system to create a commercially supportable
+      build system for embedded Linux. After Intel Corporation acquired
+      OpenedHand, the poky project became the basis for the Yocto
+      Project's build system.
+
+-  *Recipe:* A set of instructions for building packages. A recipe
+   describes where you get source code, which patches to apply, how to
+   configure the source, how to compile it and so on. Recipes also
+   describe dependencies for libraries or for other recipes. Recipes
+   represent the logical unit of execution, the software to build, the
+   images to build, and use the ``.bb`` file extension.
+
+-  *Reference Kit:* A working example of a system, which includes a
+   `BSP <#board-support-package-bsp-term>`__ as well as a `build
+   host <#hardware-build-system-term>`__ and other components, that can
+   work on specific hardware.
+
+-  *Source Directory:* This term refers to the directory structure
+   created as a result of creating a local copy of the ``poky`` Git
+   repository ``git://git.yoctoproject.org/poky`` or expanding a
+   released ``poky`` tarball.
+
+   .. note::
+
+      Creating a local copy of the
+      poky
+      Git repository is the recommended method for setting up your
+      Source Directory.
+
+   Sometimes you might hear the term "poky directory" used to refer to
+   this directory structure.
+
+   .. note::
+
+      The OpenEmbedded build system does not support file or directory
+      names that contain spaces. Be sure that the Source Directory you
+      use does not contain these types of names.
+
+   The Source Directory contains BitBake, Documentation, Metadata and
+   other files that all support the Yocto Project. Consequently, you
+   must have the Source Directory in place on your development system in
+   order to do any development using the Yocto Project.
+
+   When you create a local copy of the Git repository, you can name the
+   repository anything you like. Throughout much of the documentation,
+   "poky" is used as the name of the top-level folder of the local copy
+   of the poky Git repository. So, for example, cloning the ``poky`` Git
+   repository results in a local Git repository whose top-level folder
+   is also named "poky".
+
+   While it is not recommended that you use tarball expansion to set up
+   the Source Directory, if you do, the top-level directory name of the
+   Source Directory is derived from the Yocto Project release tarball.
+   For example, downloading and unpacking ```` results in a Source
+   Directory whose root folder is named ````.
+
+   It is important to understand the differences between the Source
+   Directory created by unpacking a released tarball as compared to
+   cloning ``git://git.yoctoproject.org/poky``. When you unpack a
+   tarball, you have an exact copy of the files based on the time of
+   release - a fixed release point. Any changes you make to your local
+   files in the Source Directory are on top of the release and will
+   remain local only. On the other hand, when you clone the ``poky`` Git
+   repository, you have an active development repository with access to
+   the upstream repository's branches and tags. In this case, any local
+   changes you make to the local Source Directory can be later applied
+   to active development branches of the upstream ``poky`` Git
+   repository.
+
+   For more information on concepts related to Git repositories,
+   branches, and tags, see the "`Repositories, Tags, and
+   Branches <&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches>`__"
+   section in the Yocto Project Overview and Concepts Manual.
+
+-  *Task:* A unit of execution for BitBake (e.g.
+   ```do_compile`` <#ref-tasks-compile>`__,
+   ```do_fetch`` <#ref-tasks-fetch>`__,
+   ```do_patch`` <#ref-tasks-patch>`__, and so forth).
+
+-  *Toaster:* A web interface to the Yocto Project's `OpenEmbedded Build
+   System <#build-system-term>`__. The interface enables you to
+   configure and run your builds. Information about builds is collected
+   and stored in a database. For information on Toaster, see the
+   `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__.
+
+-  *Upstream:* A reference to source code or repositories that are not
+   local to the development system but located in a master area that is
+   controlled by the maintainer of the source code. For example, in
+   order for a developer to work on a particular piece of code, they
+   need to first get a copy of it from an "upstream" source.