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

diff --git a/documentation/toaster-manual/toaster-manual-intro.rst b/documentation/toaster-manual/toaster-manual-intro.rst
new file mode 100644
index 0000000000..92d8c94c52
--- /dev/null
+++ b/documentation/toaster-manual/toaster-manual-intro.rst
@@ -0,0 +1,97 @@
+************
+Introduction
+************
+
+Toaster is a web interface to the Yocto Project's `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__. The interface
+enables you to configure and run your builds. Information about builds
+is collected and stored in a database. You can use Toaster to configure
+and start builds on multiple remote build servers.
+
+.. _intro-features:
+
+Toaster Features
+================
+
+Toaster allows you to configure and run builds, and it provides
+extensive information about the build process.
+
+-  *Configure and Run Builds:* You can use the Toaster web interface to
+   configure and start your builds. Builds started using the Toaster web
+   interface are organized into projects. When you create a project, you
+   are asked to select a release, or version of the build system you
+   want to use for the project builds. As shipped, Toaster supports
+   Yocto Project releases 1.8 and beyond. With the Toaster web
+   interface, you can:
+
+   -  Browse layers listed in the various `layer
+      sources <#layer-source>`__ that are available in your project
+      (e.g. the OpenEmbedded Layer Index at
+      ` <http://layers.openembedded.org/layerindex/>`__).
+
+   -  Browse images, recipes, and machines provided by those layers.
+
+   -  Import your own layers for building.
+
+   -  Add and remove layers from your configuration.
+
+   -  Set configuration variables.
+
+   -  Select a target or multiple targets to build.
+
+   -  Start your builds.
+
+   Toaster also allows you to configure and run your builds from the
+   command line, and switch between the command line and the web
+   interface at any time. Builds started from the command line appear
+   within a special Toaster project called "Command line builds".
+
+-  *Information About the Build Process:* Toaster also records extensive
+   information about your builds. Toaster collects data for builds you
+   start from the web interface and from the command line as long as
+   Toaster is running.
+
+   .. note::
+
+      You must start Toaster before the build or it will not collect
+      build data.
+
+   With Toaster you can:
+
+   -  See what was built (recipes and packages) and what packages were
+      installed into your final image.
+
+   -  Browse the directory structure of your image.
+
+   -  See the value of all variables in your build configuration, and
+      which files set each value.
+
+   -  Examine error, warning, and trace messages to aid in debugging.
+
+   -  See information about the BitBake tasks executed and reused during
+      your build, including those that used shared state.
+
+   -  See dependency relationships between recipes, packages, and tasks.
+
+   -  See performance information such as build time, task time, CPU
+      usage, and disk I/O.
+
+For an overview of Toaster shipped with the Yocto Project DISTRO
+Release, see the "`Toaster - Yocto Project
+2.2 <https://youtu.be/BlXdOYLgPxA>`__" video.
+
+.. _toaster-installation-options:
+
+Installation Options
+====================
+
+You can set Toaster up to run as a local instance or as a shared hosted
+service.
+
+When Toaster is set up as a local instance, all the components reside on
+a single build host. Fundamentally, a local instance of Toaster is
+suited for a single user developing on a single build host.
+
+Toaster as a hosted service is suited for multiple users developing
+across several build hosts. When Toaster is set up as a hosted service,
+its components can be spread across several machines: