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, 136 insertions, 0 deletions

diff --git a/documentation/sdk-manual/sdk-using.rst b/documentation/sdk-manual/sdk-using.rst
new file mode 100644
index 0000000000..afe72d2b61
--- /dev/null
+++ b/documentation/sdk-manual/sdk-using.rst
@@ -0,0 +1,136 @@
+**********************
+Using the Standard SDK
+**********************
+
+This chapter describes the standard SDK and how to install it.
+Information includes unique installation and setup aspects for the
+standard SDK.
+
+.. note::
+
+   For a side-by-side comparison of main features supported for a
+   standard SDK as compared to an extensible SDK, see the "
+   Introduction
+   " section.
+
+You can use a standard SDK to work on Makefile and Autotools-based
+projects. See the "`Using the SDK Toolchain
+Directly <#sdk-working-projects>`__" chapter for more information.
+
+.. _sdk-standard-sdk-intro:
+
+Why use the Standard SDK and What is in It?
+===========================================
+
+The Standard SDK provides a cross-development toolchain and libraries
+tailored to the contents of a specific image. You would use the Standard
+SDK if you want a more traditional toolchain experience as compared to
+the extensible SDK, which provides an internal build system and the
+``devtool`` functionality.
+
+The installed Standard SDK consists of several files and directories.
+Basically, it contains an SDK environment setup script, some
+configuration files, and host and target root filesystems to support
+usage. You can see the directory structure in the "`Installed Standard
+SDK Directory
+Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
+
+.. _sdk-installing-the-sdk:
+
+Installing the SDK
+==================
+
+The first thing you need to do is install the SDK on your `Build
+Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
+``*.sh`` installation script.
+
+You can download a tarball installer, which includes the pre-built
+toolchain, the ``runqemu`` script, and support files from the
+appropriate `toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within
+the Index of Releases. Toolchains are available for several 32-bit and
+64-bit architectures with the ``x86_64`` directories, respectively. The
+toolchains the Yocto Project provides are based off the
+``core-image-sato`` and ``core-image-minimal`` images and contain
+libraries appropriate for developing against that image.
+
+The names of the tarball installer scripts are such that a string
+representing the host system appears first in the filename and then is
+immediately followed by a string representing the target architecture.
+poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
+Where: host_system is a string representing your development system:
+i686 or x86_64. image_type is the image for which the SDK was built:
+core-image-minimal or core-image-sato. arch is a string representing the
+tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2,
+mips64, ppc7400, or cortexa8hf-neon. release_version is a string
+representing the release number of the Yocto Project: DISTRO,
+DISTRO+snapshot For example, the following SDK installer is for a 64-bit
+development host system and a i586-tuned target architecture based off
+the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
+poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
+
+.. note::
+
+   As an alternative to downloading an SDK, you can build the SDK
+   installer. For information on building the installer, see the "
+   Building an SDK Installer
+   " section.
+
+The SDK and toolchains are self-contained and by default are installed
+into the ``poky_sdk`` folder in your home directory. You can choose to
+install the extensible SDK in any location when you run the installer.
+However, because files need to be written under that directory during
+the normal course of operation, the location you choose for installation
+must be writable for whichever users need to use the SDK.
+
+The following command shows how to run the installer given a toolchain
+tarball for a 64-bit x86 development host system and a 64-bit x86 target
+architecture. The example assumes the SDK installer is located in
+``~/Downloads/`` and has execution rights.
+
+.. note::
+
+   If you do not have write permissions for the directory into which you
+   are installing the SDK, the installer notifies you and exits. For
+   that case, set up the proper permissions in the directory and run the
+   installer again.
+
+$ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
+Poky (Yocto Project Reference Distro) SDK installer version DISTRO
+=============================================================== Enter
+target directory for SDK (default: /opt/poky/DISTRO): You are about to
+install the SDK to "/opt/poky/DISTRO". Proceed [Y/n]? Y Extracting
+SDK........................................
+..............................done Setting it up...done SDK has been
+successfully set up and is ready to be used. Each time you wish to use
+the SDK in a new shell session, you need to source the environment setup
+script e.g. $ . /opt/poky/DISTRO/environment-setup-i586-poky-linux
+
+Again, reference the "`Installed Standard SDK Directory
+Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
+for more details on the resulting directory structure of the installed
+SDK.
+
+.. _sdk-running-the-sdk-environment-setup-script:
+
+Running the SDK Environment Setup Script
+========================================
+
+Once you have the SDK installed, you must run the SDK environment setup
+script before you can actually use the SDK. This setup script resides in
+the directory you chose when you installed the SDK, which is either the
+default ``/opt/poky/DISTRO`` directory or the directory you chose during
+installation.
+
+Before running the script, be sure it is the one that matches the
+architecture for which you are developing. Environment setup scripts
+begin with the string "``environment-setup``" and include as part of
+their name the tuned target architecture. As an example, the following
+commands set the working directory to where the SDK was installed and
+then source the environment setup script. In this example, the setup
+script is for an IA-based target machine using i586 tuning: $ source
+/opt/poky/DISTRO/environment-setup-i586-poky-linux When you run the
+setup script, the same environment variables are defined as are when you
+run the setup script for an extensible SDK. See the "`Running the
+Extensible SDK Environment Setup
+Script <#sdk-running-the-extensible-sdk-environment-setup-script>`__"
+section for more information.