Documentation: Restructured toplevel documentationdocs-reorganization

This is intended to make things easier to find for the
various types of people searching for stuff.

  o The installation instructions remain on the main page.

  o Three main separate pages have been created
    - Using BuildStream
    - Authoring BuildStream projects
    - Core API reference, for plugin authors

  o The "Authoring projects" section swallows the
    previous plugin index; so one can find the plugin one
    is looking for on the same page as the rest of the format
    docs

  o The plugin authoring section has been swallowed by the
    core API reference section, with a note that this is useful
    especially for plugin authors.

5 files changed, 90 insertions, 70 deletions

diff --git a/doc/source/format.rst b/doc/source/format.rst
index 6f6e2f0ec..fe4f57ea1 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -91,6 +91,8 @@ to the elements on which they depend here. See `Dependencies`_ for more informat
 on the dependency model.
 
 
+.. _format_sources:
+
 Sources
 ~~~~~~~
 
@@ -167,6 +169,8 @@ build instructions are run for this element.
 Environment variables can also be declared and overridden in the :ref:`projectconf`
 
 
+.. _format_config:
+
 Config
 ~~~~~~
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8bf871989..36aa749bc 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -29,60 +29,12 @@ Installing
 * :ref:`artifacts`
 
 
-Running
--------
-* :ref:`invoking`
-* :ref:`config`
+Documentation
+-------------
 
-
-Project format
---------------
-* :ref:`formatintro`
-
-  * :ref:`format_structure`
-  * :ref:`format_composition`
-  * :ref:`format_directives`
-
-* :ref:`projectconf`
-
-  * :ref:`project_essentials`
-  * :ref:`project_plugins`
-  * :ref:`project_options`
-  * :ref:`project_defaults`
-  * :ref:`project_builtin_defaults`
-
-* :ref:`format`
-
-  * :ref:`format_basics`
-  * :ref:`format_dependencies`
-  * :ref:`format_variables`
-
-* :ref:`public`
-
-
-Builtin Plugins
----------------
-* :ref:`plugins`
-
-  * :ref:`plugins_elements`
-  * :ref:`plugins_sources`
-
-External Plugins
-----------------
-
-* `bst-external <http://buildstream.gitlab.io/bst-external/>`_
-
-
-Creating Plugins
-----------------
-* :ref:`pluginauthoring`
-
-  * :ref:`core_framework`
-
-
-Internals
----------
-* :ref:`cachekeys`
+* :ref:`main_using`
+* :ref:`main_authoring`
+* :ref:`main_core`
 
 
 Indices and tables
diff --git a/doc/source/pluginindex.rst b/doc/source/main_authoring.rst
index 57f14876d..4e118f8af 100644
--- a/doc/source/pluginindex.rst
+++ b/doc/source/main_authoring.rst
@@ -1,28 +1,64 @@
 :orphan:
 
-.. _plugins:
 
-Plugins
-=======
+.. _main_authoring:
+
+Authoring Projects
+==================
+This section details how to use the BuildStream YAML format to
+create your own project or modify existing projects.
+
+
+Project format
+--------------
+* :ref:`formatintro`
+
+  * :ref:`format_structure`
+  * :ref:`format_composition`
+  * :ref:`format_directives`
 
+* :ref:`projectconf`
+
+  * :ref:`project_essentials`
+  * :ref:`project_plugins`
+  * :ref:`project_options`
+  * :ref:`project_defaults`
+  * :ref:`project_builtin_defaults`
+
+* :ref:`format`
+
+  * :ref:`format_basics`
+  * :ref:`format_dependencies`
+  * :ref:`format_variables`
+
+* :ref:`public`
+
+
+Plugins
+-------
+Plugins provide their own individual plugin specific YAML configurations,
+The element ``.bst`` files can specify plugin specific configuration in
+the :ref:`config section <format_config>`, while sources declared on a
+given element specify their plugin specific configuration
+:ref:`directly on their main dictionary <format_sources>`.
 
-.. _plugins_elements:
 
 Elements
---------
+~~~~~~~~
 The following element types are provided with BuildStream:
 
 
 General Elements
-~~~~~~~~~~~~~~~~
+''''''''''''''''
 
 * :mod:`stack <elements.stack>` - Symbolic Element for dependency grouping
 * :mod:`import <elements.import>` - Import sources directly
 * :mod:`compose <elements.compose>` - Compose the output of multiple elements
 * :mod:`script <elements.script>` - Run scripts to create output
 
+
 Build Elements
-~~~~~~~~~~~~~~
+''''''''''''''
 
 * :mod:`manual <elements.manual>` - Manual Build Element
 * :mod:`autotools <elements.autotools>` - Autotools Build Element
@@ -35,11 +71,8 @@ Build Elements
 * :mod:`pip <elements.pip>` - Pip build element
 
 
-.. _plugins_sources:
-
-
 Sources
---------
+~~~~~~~
 The following source types are provided with BuildStream:
 
 * :mod:`local <sources.local>` - A Source implementation for local files and directories
@@ -49,3 +82,12 @@ The following source types are provided with BuildStream:
 * :mod:`bzr <sources.bzr>` - A Source implementation for bazaar
 * :mod:`ostree <sources.ostree>` - A Source implementation for ostree
 * :mod:`patch <sources.patch>` - A Source implementation for applying local patches
+
+
+
+External Plugins
+----------------
+External plugins need to be installed separately, here is
+a list of BuildStream plugin projects known to us at this time:
+
+* `bst-external <http://buildstream.gitlab.io/bst-external/>`_
diff --git a/doc/source/pluginauthoring.rst b/doc/source/main_core.rst
index c42bd575b..b14413591 100644
--- a/doc/source/pluginauthoring.rst
+++ b/doc/source/main_core.rst
@@ -1,12 +1,12 @@
 :orphan:
 
-.. _pluginauthoring:
 
+.. _main_core:
 
-Authoring Plugins
-=================
-Here we try to provide any additional documentation one will need
-to create their own custom plugins to use with BuildStream.
+Core documentation and reference
+================================
+This section details the core API reference along with
+other more elaborate details about BuildStream internals.
 
 
 .. _core_framework:
@@ -15,7 +15,8 @@ Core Framework
 --------------
 The core public APIs are of interest to anyone who wishes to
 implement custom :mod:`Element <buildstream.element>` or
-:mod:`Source <buildstream.source>` plugins.
+:mod:`Source <buildstream.source>` plugins, and can also be
+useful for working on BuildStream itself.
 
 * :mod:`Plugin <buildstream.plugin>` - Base Class for all plugins
 * :mod:`Source <buildstream.source>` - Base Source Class
@@ -24,3 +25,8 @@ implement custom :mod:`Element <buildstream.element>` or
 * :mod:`ScriptElement <buildstream.scriptelement>` - Script Element Class
 * :mod:`Sandbox <buildstream.sandbox.sandbox>` - Build Sandbox
 * :mod:`Utilities <buildstream.utils>` - Utilities for Plugins
+
+
+Internals
+---------
+* :ref:`cachekeys`
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
new file mode 100644
index 000000000..b817e0cda
--- /dev/null
+++ b/doc/source/main_using.rst
@@ -0,0 +1,16 @@
+:orphan:
+
+
+.. _main_using:
+
+Using BuildStream
+=================
+This section details how to use the BuildStream command line interface
+and work with existing BuildStream projects.
+
+For details on how to modify an existing BuildStream project or create
+a new one, refer to :ref:`main_authoring`.
+
+  
+* :ref:`invoking`
+* :ref:`config`