doc/source/examples_flatpak_autotools.rst: Enhanced exampletristan/flatpak-example

This has now changed to:

  * Have explanations of the project.conf and each element
    in the example, explaining what they are for

  * Have links into the reference for the specific features
    this example uses, such that the reader can get familiar
    with the reference manual from example windows

1 files changed, 117 insertions, 12 deletions

diff --git a/doc/source/examples_flatpak_autotools.rst b/doc/source/examples_flatpak_autotools.rst
index d30e5435d..2c03fa621 100644
--- a/doc/source/examples_flatpak_autotools.rst
+++ b/doc/source/examples_flatpak_autotools.rst
@@ -1,33 +1,138 @@
 
 .. _examples_flatpak_autotools:
 
-Using flatpak runtimes to build and run from source
-===================================================
+Building on a Flatpak SDK
+=========================
 Here we demonstrate how to build and run software using
 a Flatpak SDK for the base runtime.
 
-Config files
 
-- project.conf
+Project structure
+-----------------
+
+
+project.conf
+~~~~~~~~~~~~
+The following is a simple :ref:`project <projectconf>` definition:
 
 .. literalinclude:: ../examples/flatpak-autotools/project.conf
    :language: yaml
 
-- element
+Here we use an :ref:`arch option <project_options_arch>` to allow
+conditional statements in this project to be made depending on machine
+architecture. For this example we only support the ``i386`` and ``x86_64``
+architectures.
+
+Note that we've added a :ref:`source alias <project_source_aliases>` for
+the ``https://sdk.gnome.org/`` repository to download the SDK from.
+
+
+base/sdk.bst
+~~~~~~~~~~~~
+This is the :mod:`import <elements.import>` element used to import the
+actual Flatpak SDK, it uses an :mod:`ostree <sources.ostree>` source to
+download the Flatpak since these are hosted in OSTree repositories.
 
-.. literalinclude:: ../examples/flatpak-autotools/elements/flatpak-autotools.bst
+.. literalinclude:: ../examples/flatpak-autotools/elements/base/sdk.bst
    :language: yaml
 
-- element
+While declaring the :mod:`ostree <sources.ostree>` source, we specify a GPG
+public key to verify the OSTree download. This configuration is optional
+but recommended for OSTree repositories. The key is stored in the project directory
+at ``keys/gnome-sdk.gpg``.
+
+We also use :ref:`conditional statements <format_directives_conditional>` to decide
+which branch to download.
+
+For the ``config`` section of this :mod:`import <elements.import>` element,
+it's important to note two things:
+
+* **source**: We only want to extract the ``files/`` directory from the SDK,
+
+  This is becase Flatpak runtimes dont start at the root of the OSTree checkout,
+  instead the actual files start in the ``files//`` subdirectory
 
-.. literalinclude:: ../examples/flatpak-autotools/elements/dependencies/usrmerge.bst
+* **target**: The content we've extracted should be staged at ``/usr``
+
+  This is because Flatpak runtimes only contain the data starting at ``/usr``,
+  and they expect to be staged at ``/usr`` at runtime, in an environment
+  with the appropriate symlinks setup from ``/``.
+
+
+base/usrmerge.bst
+~~~~~~~~~~~~~~~~~
+This is another :mod:`import <elements.import>` element, and it uses
+the :mod:`local <sources.local>` source type so that we can stage files
+literally stored in the same repository as the project.
+
+.. literalinclude:: ../examples/flatpak-autotools/elements/base/usrmerge.bst
    :language: yaml
 
-Building::
+The purpose of this element is simply to add the symlinks for
+``/lib -> /usr/lib``, ``/bin -> /usr/bin`` and ``/etc -> /usr/etc``, we
+have it depend on the ``base/sdk.bst`` element only to ensure that
+it is staged *after*, i.e. the symlinks are created after the SDK is staged.
+
+As suggested by the ``.bst`` file, the symlinks themselves are a part
+of the project and they are stored in the ``files/links`` directory.
+
+
+base.bst
+~~~~~~~~
+This is just a :mod:`stack <elements.stack>` element for convenience sake.
+
+.. literalinclude:: ../examples/flatpak-autotools/elements/base.bst
+   :language: yaml
+
+Often times you will have a more complex base to build things on, and it
+is convenient to just use a :mod:`stack <elements.stack>` element for
+your elements to depend on without needing to know about the inner workings
+of the base system build.
+
+
+hello.bst
+~~~~~~~~~
+Finally, we show an example of an :mod:`autotools <elements.autotools>` element
+to build our sample "Hello World" program.
+
+.. literalinclude:: ../examples/flatpak-autotools/elements/hello.bst
+   :language: yaml
+
+We use another :mod:`local <sources.local>` source to obtain the sample
+autotools project, but normally you would probably use a :mod:`git <sources.git>`
+or other source to obtain source code from another repository.
+
+
+Using the project
+-----------------
+Now that we've explained the basic layout of the project, here are
+just a few things you can try to do with the project.
+
+
+.. note::
+
+   The following examples assume that you have first changed your working
+   directory to the project root.
+
+   This example is a part of the BuildStream source repository in
+   the doc/examples/flatpak-autotools subdirectory.
+
+
+Build the hello.bst element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To build the project, run :ref:`bst build <invoking_build>` in the
+following way::
+
+   bst build hello.bst
 
-   bst build flatpak-autotools.bst
 
-Running::
+Run the hello world program
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The hello world program has been built into the standard ``/usr`` prefix,
+and will automatically be in the default ``PATH`` for running things
+in a :ref:`bst shell <invoking_shell>`.
 
-   bst shell flatpak-autotools.bst hello
+To just run the program, run :ref:`bst shell <invoking_shell>` in the
+following way::
 
+   bst shell hello.bst -- hello