doc: Added plugins as ToC elements instead of orphaned links

  o Now the page titles are declared in plugins, allowing for
    a more descriptive ToC

  o Makefile and plugin.rsttemplate updated to not produce the title,
    to no longer use `:orphan:` for plugin pages, and to ignore any
    private modules in the plugin directories.

  o Interestingly, now the docs will fail to build if you add
    a new plugin and forget to add it to the documentation.

buildstream/plugins/elements/autotools.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Autotools build element
-
+"""
+autotools - Autotools build element
+===================================
 This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
 using Autotools build scripts (also known as the `GNU Build System
 <https://en.wikipedia.org/wiki/GNU_Build_System>`_).

buildstream/plugins/elements/cmake.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""CMake build element
-
+"""
+cmake - CMake build element
+===========================
 This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
 using the `CMake <https://cmake.org/>`_ build system.
 

buildstream/plugins/elements/compose.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Compose element
-
+"""
+compose - Compose the output of multiple elements
+=================================================
 This element creates a selective composition of its dependencies.
 
 This is normally used at near the end of a pipeline to prepare

buildstream/plugins/elements/distutils.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Python Distutils element
-
+"""
+distutils - Python distutils element
+====================================
 A :mod:`BuildElement <buildstream.buildelement>` implementation for using
 python distutils
 

buildstream/plugins/elements/filter.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Jonathan Maw <jonathan.maw@codethink.co.uk>
 
-"""Filter element
-
+"""
+filter - Extract a subset of files from another element
+=======================================================
 This filters another element by producing an output that is a subset of
 the filtered element.
 

buildstream/plugins/elements/import.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Import element
-
+"""
+import - Import sources directly
+================================
 Import elements produce artifacts directly from its sources
 without any kind of processing. These are typically used to
 import an SDK to build on top of or to overlay your build with

buildstream/plugins/elements/junction.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Jürg Billeter <juerg.billeter@codethink.co.uk>
 
-"""Junction element
-
+"""
+junction - Integrate subprojects
+================================
 This element is a link to another BuildStream project. It allows integration
 of multiple projects into a single pipeline.
 

buildstream/plugins/elements/make.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Ed Baunton <ebaunton1@bloomberg.net>
 
-"""Make build element
-
+"""
+make - Make build element
+=========================
 This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
 using GNU make based build.
 

buildstream/plugins/elements/makemaker.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Perl MakeMaker build element
-
+"""
+makemaker - Perl MakeMaker build element
+========================================
 A :mod:`BuildElement <buildstream.buildelement>` implementation for using
 the Perl ExtUtil::MakeMaker build system
 

buildstream/plugins/elements/manual.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Manual build element
-
+"""
+manual - Manual build element
+=============================
 The most basic build element does nothing but allows users to
 add custom build commands to the array understood by the :mod:`BuildElement <buildstream.buildelement>`
 

buildstream/plugins/elements/meson.py

@@ -14,8 +14,9 @@
 #  You should have received a copy of the GNU Lesser General Public
 #  License along with this library. If not, see <http://www.gnu.org/licenses/>.
 
-"""Meson build element
-
+"""
+meson - Meson build element
+===========================
 This is a :mod:`BuildElement <buildstream.buildelement>` implementation for
 using `Meson <http://mesonbuild.com/>`_ build scripts.
 

buildstream/plugins/elements/modulebuild.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Perl Module::Build build element
-
+"""
+modulebuild - Perl Module::Build build element
+==============================================
 A :mod:`BuildElement <buildstream.buildelement>` implementation for using
 the Perl Module::Build build system
 

buildstream/plugins/elements/pip.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Mathieu Bridon <bochecha@daitauha.fr>
 
-"""Pip build element
-
+"""
+pip - Pip build element
+=======================
 A :mod:`BuildElement <buildstream.buildelement>` implementation for installing
 Python modules with pip
 

buildstream/plugins/elements/qmake.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""CMake build element
-
+"""
+qmake - QMake build element
+===========================
 A :mod:`BuildElement <buildstream.buildelement>` implementation for using
 the qmake build system
 

buildstream/plugins/elements/script.py

@@ -19,8 +19,9 @@
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 #        Jonathan Maw <jonathan.maw@codethink.co.uk>
 
-"""Script element
-
+"""
+script - Run scripts to create output
+=====================================
 This element allows one to run some commands to mutate the
 input and create some output.
 

buildstream/plugins/elements/stack.py

@@ -18,8 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""Stack element
-
+"""
+stack - Symbolic Element for dependency grouping
+================================================
 Stack elements are simply a symbolic element used for representing
 a logical group of elements.
 """

buildstream/plugins/sources/bzr.py

@@ -17,7 +17,9 @@
 #  Authors:
 #        Jonathan Maw <jonathan.maw@codethink.co.uk>
 
-"""A source implementation for staging bazaar branches
+"""
+bzr - stage files from a bazaar repository
+==========================================
 
 **Usage:**
 

buildstream/plugins/sources/deb.py

@@ -19,7 +19,9 @@
 #        Jonathan Maw <jonathan.maw@codethink.co.uk>
 #        Richard Maw <richard.maw@codethink.co.uk>
 
-"""A source implementation for staging deb files
+"""
+deb - stage files from .deb packages
+====================================
 
 **Usage:**
 

buildstream/plugins/sources/git.py

@@ -18,7 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""A Source implementation for staging git checkouts
+"""
+git - stage files from a git repository
+=======================================
 
 **Usage:**
 

buildstream/plugins/sources/local.py

@@ -18,7 +18,9 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-"""A Source implementation for staging local project files
+"""
+local - stage local files and directories
+=========================================
 
 **Usage:**