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

diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst
new file mode 100644
index 0000000000..42f8bfeb46
--- /dev/null
+++ b/documentation/sdk-manual/sdk-working-projects.rst
@@ -0,0 +1,284 @@
+********************************
+Using the SDK Toolchain Directly
+********************************
+
+You can use the SDK toolchain directly with Makefile and Autotools-based
+projects.
+
+Autotools-Based Projects
+========================
+
+Once you have a suitable `cross-development
+toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__
+installed, it is very easy to develop a project using the `GNU
+Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
+workflow, which is outside of the `OpenEmbedded build
+system <&YOCTO_DOCS_REF_URL;#build-system-term>`__.
+
+The following figure presents a simple Autotools workflow.
+
+Follow these steps to create a simple Autotools-based "Hello World"
+project:
+
+.. note::
+
+   For more information on the GNU Autotools workflow, see the same
+   example on the
+   GNOME Developer
+   site.
+
+1. *Create a Working Directory and Populate It:* Create a clean
+   directory for your project and then make that directory your working
+   location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
+   setting up the directory, populate it with files needed for the flow.
+   You need a project source file, a file to help with configuration,
+   and a file to help create the Makefile, and a README file:
+   ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
+   respectively.
+
+   Use the following command to create an empty README file, which is
+   required by GNU Coding Standards: $ touch README Create the remaining
+   three files as follows:
+
+   -  *``hello.c``:* #include <stdio.h> main() { printf("Hello
+      World!\n"); }
+
+   -  *``configure.ac``:* AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign])
+      AC_PROG_CC AC_CONFIG_FILES(Makefile) AC_OUTPUT
+
+   -  *``Makefile.am``:* bin_PROGRAMS = hello hello_SOURCES = hello.c
+
+2. *Source the Cross-Toolchain Environment Setup File:* As described
+   earlier in the manual, installing the cross-toolchain creates a
+   cross-toolchain environment setup script in the directory that the
+   SDK was installed. Before you can use the tools to develop your
+   project, you must source this setup script. The script begins with
+   the string "environment-setup" and contains the machine architecture,
+   which is followed by the string "poky-linux". For this example, the
+   command sources a script from the default SDK installation directory
+   that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
+   Project release: $ source
+   /opt/poky/DISTRO/environment-setup-i586-poky-linux
+
+3. *Create the ``configure`` Script:* Use the ``autoreconf`` command to
+   generate the ``configure`` script. $ autoreconf The ``autoreconf``
+   tool takes care of running the other Autotools such as ``aclocal``,
+   ``autoconf``, and ``automake``.
+
+   .. note::
+
+      If you get errors from
+      configure.ac
+      , which
+      autoreconf
+      runs, that indicate missing files, you can use the "-i" option,
+      which ensures missing auxiliary files are copied to the build
+      host.
+
+4. *Cross-Compile the Project:* This command compiles the project using
+   the cross-compiler. The
+   ```CONFIGURE_FLAGS`` <&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS>`__
+   environment variable provides the minimal arguments for GNU
+   configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based
+   project, you can use the cross-toolchain by just passing the
+   appropriate host option to ``configure.sh``. The host option you use
+   is derived from the name of the environment setup script found in the
+   directory in which you installed the cross-toolchain. For example,
+   the host option for an ARM-based target that uses the GNU EABI is
+   ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
+   script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
+   following command works to update your project and rebuild it using
+   the appropriate cross-toolchain tools: $ ./configure
+   --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
+
+5. *Make and Install the Project:* These two commands generate and
+   install the project into the destination directory: $ make $ make
+   install DESTDIR=./tmp
+
+   .. note::
+
+      To learn about environment variables established when you run the
+      cross-toolchain environment setup script and how they are used or
+      overridden when the Makefile, see the "
+      Makefile-Based Projects
+      " section.
+
+   This next command is a simple way to verify the installation of your
+   project. Running the command prints the architecture on which the
+   binary file can run. This architecture should be the same
+   architecture that the installed cross-toolchain supports. $ file
+   ./tmp/usr/local/bin/hello
+
+6. *Execute Your Project:* To execute the project, you would need to run
+   it on your target hardware. If your target hardware happens to be
+   your build host, you could run the project as follows: $
+   ./tmp/usr/local/bin/hello As expected, the project displays the
+   "Hello World!" message.
+
+Makefile-Based Projects
+=======================
+
+Simple Makefile-based projects use and interact with the cross-toolchain
+environment variables established when you run the cross-toolchain
+environment setup script. The environment variables are subject to
+general ``make`` rules.
+
+This section presents a simple Makefile development flow and provides an
+example that lets you see how you can use cross-toolchain environment
+variables and Makefile variables during development.
+
+The main point of this section is to explain the following three cases
+regarding variable behavior:
+
+-  *Case 1 - No Variables Set in the ``Makefile`` Map to Equivalent
+   Environment Variables Set in the SDK Setup Script:* Because matching
+   variables are not specifically set in the ``Makefile``, the variables
+   retain their values based on the environment setup script.
+
+-  *Case 2 - Variables Are Set in the Makefile that Map to Equivalent
+   Environment Variables from the SDK Setup Script:* Specifically
+   setting matching variables in the ``Makefile`` during the build
+   results in the environment settings of the variables being
+   overwritten. In this case, the variables you set in the ``Makefile``
+   are used.
+
+-  *Case 3 - Variables Are Set Using the Command Line that Map to
+   Equivalent Environment Variables from the SDK Setup Script:*
+   Executing the ``Makefile`` from the command line results in the
+   environment variables being overwritten. In this case, the
+   command-line content is used.
+
+.. note::
+
+   Regardless of how you set your variables, if you use the "-e" option
+   with
+   make
+   , the variables from the SDK setup script take precedence:
+   ::
+
+           $ make -e target
+                      
+
+The remainder of this section presents a simple Makefile example that
+demonstrates these variable behaviors.
+
+In a new shell environment variables are not established for the SDK
+until you run the setup script. For example, the following commands show
+a null value for the compiler variable (i.e.
+```CC`` <&YOCTO_DOCS_REF_URL;#var-CC>`__). $ echo ${CC} $ Running the
+SDK setup script for a 64-bit build host and an i586-tuned target
+architecture for a ``core-image-sato`` image using the current DISTRO
+Yocto Project release and then echoing that variable shows the value
+established through the script: $ source
+/opt/poky/DISTRO/environment-setup-i586-poky-linux $ echo ${CC}
+i586-poky-linux-gcc -m32 -march=i586
+--sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
+
+To illustrate variable use, work through this simple "Hello World!"
+example:
+
+1. *Create a Working Directory and Populate It:* Create a clean
+   directory for your project and then make that directory your working
+   location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
+   setting up the directory, populate it with files needed for the flow.
+   You need a ``main.c`` file from which you call your function, a
+   ``module.h`` file to contain headers, and a ``module.c`` that defines
+   your function.
+
+   Create the three files as follows:
+
+   -  *``main.c``:* #include "module.h" void sample_func(); int main() {
+      sample_func(); return 0; }
+
+   -  *``module.h``:* #include <stdio.h> void sample_func();
+
+   -  *``module.c``:* #include "module.h" void sample_func() {
+      printf("Hello World!"); printf("\n"); }
+
+2. *Source the Cross-Toolchain Environment Setup File:* As described
+   earlier in the manual, installing the cross-toolchain creates a
+   cross-toolchain environment setup script in the directory that the
+   SDK was installed. Before you can use the tools to develop your
+   project, you must source this setup script. The script begins with
+   the string "environment-setup" and contains the machine architecture,
+   which is followed by the string "poky-linux". For this example, the
+   command sources a script from the default SDK installation directory
+   that uses the 32-bit Intel x86 Architecture and the DISTRO_NAME Yocto
+   Project release: $ source
+   /opt/poky/DISTRO/environment-setup-i586-poky-linux
+
+3. *Create the ``Makefile``:* For this example, the Makefile contains
+   two lines that can be used to set the ``CC`` variable. One line is
+   identical to the value that is set when you run the SDK environment
+   setup script, and the other line sets ``CC`` to "gcc", the default
+   GNU compiler on the build host: # CC=i586-poky-linux-gcc -m32
+   -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux #
+   CC="gcc" all: main.o module.o ${CC} main.o module.o -o target_bin
+   main.o: main.c module.h ${CC} -I . -c main.c module.o: module.c
+   module.h ${CC} -I . -c module.c clean: rm -rf \*.o rm target_bin
+
+4. *Make the Project:* Use the ``make`` command to create the binary
+   output file. Because variables are commented out in the Makefile, the
+   value used for ``CC`` is the value set when the SDK environment setup
+   file was run: $ make i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
+   target_bin From the results of the previous command, you can see that
+   the compiler used was the compiler established through the ``CC``
+   variable defined in the setup script.
+
+   You can override the ``CC`` environment variable with the same
+   variable as set from the Makefile by uncommenting the line in the
+   Makefile and running ``make`` again. $ make clean rm -rf \*.o rm
+   target_bin # # Edit the Makefile by uncommenting the line that sets
+   CC to "gcc" # $ make gcc -I . -c main.c gcc -I . -c module.c gcc
+   main.o module.o -o target_bin As shown in the previous example, the
+   cross-toolchain compiler is not used. Rather, the default compiler is
+   used.
+
+   This next case shows how to override a variable by providing the
+   variable as part of the command line. Go into the Makefile and
+   re-insert the comment character so that running ``make`` uses the
+   established SDK compiler. However, when you run ``make``, use a
+   command-line argument to set ``CC`` to "gcc": $ make clean rm -rf
+   \*.o rm target_bin # # Edit the Makefile to comment out the line
+   setting CC to "gcc" # $ make i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
+   target_bin $ make clean rm -rf \*.o rm target_bin $ make CC="gcc" gcc
+   -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o target_bin
+   In the previous case, the command-line argument overrides the SDK
+   environment variable.
+
+   In this last case, edit Makefile again to use the "gcc" compiler but
+   then use the "-e" option on the ``make`` command line: $ make clean
+   rm -rf \*.o rm target_bin # # Edit the Makefile to use "gcc" # $ make
+   gcc -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o
+   target_bin $ make clean rm -rf \*.o rm target_bin $ make -e
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+   i586-poky-linux-gcc -m32 -march=i586
+   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
+   target_bin In the previous case, the "-e" option forces ``make`` to
+   use the SDK environment variables regardless of the values in the
+   Makefile.
+
+5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
+   use the following command: $ ./target_bin Hello World!
+
+   .. note::
+
+      If you used the cross-toolchain compiler to build
+      target_bin
+      and your build host differs in architecture from that of the
+      target machine, you need to run your project on the target device.
+
+   As expected, the project displays the "Hello World!" message.