doc: Overhaul of page names and titles

 o Giving main pages simple word titles

   This makes the main page:

   * About
   * Installing
   * Using
   * Reference
   * Contributing

 o Now named all rst files with their parent page name as a prefix.

 o Also changed some titles to make overall consistent titles.

25 files changed, 48 insertions, 46 deletions

diff --git a/HACKING.rst b/HACKING.rst
index a1cffc880..8ef82244f 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -1,5 +1,5 @@
-Hacking on BuildStream
-======================
+Contributing
+============
 Some tips and guidelines for developers hacking on BuildStream
 
 
diff --git a/README.rst b/README.rst
index f571ebff6..6f64f47a6 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
-About BuildStream
------------------
+About
+-----
 .. image:: https://gitlab.com/BuildStream/buildstream/badges/master/pipeline.svg
    :target: https://gitlab.com/BuildStream/buildstream/commits/master
 
diff --git a/buildstream/source.py b/buildstream/source.py
index 470a407ad..387ed6a99 100644
--- a/buildstream/source.py
+++ b/buildstream/source.py
@@ -18,7 +18,7 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 """
-Source - base source class
+Source - Base source class
 ==========================
 
 
diff --git a/doc/source/cachekeys.rst b/doc/source/additional_cachekeys.rst
index f0df796c5..f0df796c5 100644
--- a/doc/source/cachekeys.rst
+++ b/doc/source/additional_cachekeys.rst
diff --git a/doc/source/sandboxing.rst b/doc/source/additional_sandboxing.rst
index 531a3e5d5..531a3e5d5 100644
--- a/doc/source/sandboxing.rst
+++ b/doc/source/additional_sandboxing.rst
diff --git a/doc/source/core_additional.rst b/doc/source/core_additional.rst
index 10b74cbd2..76e523ee8 100644
--- a/doc/source/core_additional.rst
+++ b/doc/source/core_additional.rst
@@ -6,5 +6,5 @@ Additional writings
 .. toctree::
    :maxdepth: 2
 
-   cachekeys
-   sandboxing
+   additional_cachekeys
+   additional_sandboxing
diff --git a/doc/source/core_format.rst b/doc/source/core_format.rst
new file mode 100644
index 000000000..294867f27
--- /dev/null
+++ b/doc/source/core_format.rst
@@ -0,0 +1,17 @@
+
+
+Project format
+==============
+This section details how to use the BuildStream YAML format to
+create your own project or modify existing projects.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Project format
+
+   format_intro
+   format_project
+   format_declaring
+   format_public
+   format_project_refs
diff --git a/doc/source/core_framework.rst b/doc/source/core_framework.rst
index 5f0db07ab..c3b84a9b1 100644
--- a/doc/source/core_framework.rst
+++ b/doc/source/core_framework.rst
@@ -2,8 +2,8 @@
 
 .. _core_framework:
 
-Core framework
---------------
+Plugin API reference
+====================
 The core public APIs are of interest to anyone who wishes to
 implement custom :mod:`Element <buildstream.element>` or
 :mod:`Source <buildstream.source>` plugins, and can also be
diff --git a/doc/source/authoring.rst b/doc/source/core_plugins.rst
index 4dca72b03..e038c2ef9 100644
--- a/doc/source/authoring.rst
+++ b/doc/source/core_plugins.rst
@@ -1,24 +1,7 @@
 
 
-Authoring projects
-==================
-This section details how to use the BuildStream YAML format to
-create your own project or modify existing projects.
-
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Project format
-
-   formatintro
-   projectconf
-   format
-   public
-   projectrefs
-
-
-Plugins
--------
+Plugin specific documentation
+=============================
 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
@@ -27,7 +10,7 @@ given element specify their plugin specific configuration directly
 
 
 General elements
-~~~~~~~~~~~~~~~~
+----------------
 .. toctree::
    :maxdepth: 1
 
@@ -40,7 +23,7 @@ General elements
 
 
 Build elements
-~~~~~~~~~~~~~~
+--------------
 .. toctree::
    :maxdepth: 1
 
@@ -57,7 +40,7 @@ Build elements
 
 
 Sources
-~~~~~~~
+-------
 .. toctree::
    :maxdepth: 1
 
diff --git a/doc/source/format.rst b/doc/source/format_declaring.rst
index 2b9e0ea25..39c099dcf 100644
--- a/doc/source/format.rst
+++ b/doc/source/format_declaring.rst
@@ -1,5 +1,6 @@
 
-Element constructs
+
+Declaring elements
 ==================
 
 
diff --git a/doc/source/formatintro.rst b/doc/source/format_intro.rst
index b1780f9dc..b1780f9dc 100644
--- a/doc/source/formatintro.rst
+++ b/doc/source/format_intro.rst
diff --git a/doc/source/projectconf.rst b/doc/source/format_project.rst
index 6174ee728..6174ee728 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/format_project.rst
diff --git a/doc/source/projectrefs.rst b/doc/source/format_project_refs.rst
index 799b5e761..799b5e761 100644
--- a/doc/source/projectrefs.rst
+++ b/doc/source/format_project_refs.rst
diff --git a/doc/source/public.rst b/doc/source/format_public.rst
index e640de7bb..e640de7bb 100644
--- a/doc/source/public.rst
+++ b/doc/source/format_public.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 16a2df3e8..5c4a62007 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -17,7 +17,7 @@ Later sections provide detailed information on BuilStream internals.
 .. toctree::
    :maxdepth: 1
 
-   about
+   main_about
    main_install
    main_using
    main_core
diff --git a/doc/source/artifacts.rst b/doc/source/install_artifacts.rst
index e0808e8fe..e0808e8fe 100644
--- a/doc/source/artifacts.rst
+++ b/doc/source/install_artifacts.rst
diff --git a/doc/source/docker.rst b/doc/source/install_docker.rst
index 9b0f8aa73..9b0f8aa73 100644
--- a/doc/source/docker.rst
+++ b/doc/source/install_docker.rst
diff --git a/doc/source/install.rst b/doc/source/install_main.rst
index 500c94ac2..500c94ac2 100644
--- a/doc/source/install.rst
+++ b/doc/source/install_main.rst
diff --git a/doc/source/about.rst b/doc/source/main_about.rst
index a6210d3d8..a6210d3d8 100644
--- a/doc/source/about.rst
+++ b/doc/source/main_about.rst
diff --git a/doc/source/main_core.rst b/doc/source/main_core.rst
index 9e43bef6e..c0757b7fa 100644
--- a/doc/source/main_core.rst
+++ b/doc/source/main_core.rst
@@ -1,7 +1,7 @@
 
 
-Reference documentation
-=======================
+Reference
+=========
 This section details the core API reference along with
 other more elaborate details about BuildStream internals.
 
@@ -9,7 +9,8 @@ other more elaborate details about BuildStream internals.
 .. toctree::
    :maxdepth: 2
 
-   authoring
+   core_format
+   core_plugins
    core_framework
    core_additional
 
diff --git a/doc/source/main_install.rst b/doc/source/main_install.rst
index 31e4680fb..c65e7ca96 100644
--- a/doc/source/main_install.rst
+++ b/doc/source/main_install.rst
@@ -1,12 +1,12 @@
 
-Installing
-==========
+Install
+=======
 This section covers how to install BuildStream onto your machine, how to run BuildStream inside a docker image and also how to configure an artifact server.
 
 
 .. toctree::
    :maxdepth: 2
 
-   install
-   docker
-   artifacts
+   install_main
+   install_docker
+   install_artifacts
diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst
index 62846baf8..dc0f5e69b 100644
--- a/doc/source/main_using.rst
+++ b/doc/source/main_using.rst
@@ -1,12 +1,12 @@
 
-Using BuildStream
-=================
+Using
+=====
 This section details how to use the BuildStream command line interface and work with existing BuildStream projects.
 
 
 .. toctree::
    :maxdepth: 2
 
-   examples
-   user_config
-   commands
+   using_examples
+   using_config
+   using_commands
diff --git a/doc/source/commands.rst b/doc/source/using_commands.rst
index 18affc6e5..18affc6e5 100644
--- a/doc/source/commands.rst
+++ b/doc/source/using_commands.rst
diff --git a/doc/source/user_config.rst b/doc/source/using_config.rst
index d02aaf3d4..d02aaf3d4 100644
--- a/doc/source/user_config.rst
+++ b/doc/source/using_config.rst
diff --git a/doc/source/examples.rst b/doc/source/using_examples.rst
index aa100d007..aa100d007 100644
--- a/doc/source/examples.rst
+++ b/doc/source/using_examples.rst