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.

16 files changed, 48 insertions, 32 deletions

diff --git a/buildstream/plugins/elements/autotools.py b/buildstream/plugins/elements/autotools.py
index 5f54c3953..93fc6be87 100644
--- a/buildstream/plugins/elements/autotools.py
+++ b/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>`_).
diff --git a/buildstream/plugins/elements/cmake.py b/buildstream/plugins/elements/cmake.py
index 292785e81..0b3de0143 100644
--- a/buildstream/plugins/elements/cmake.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/compose.py b/buildstream/plugins/elements/compose.py
index 0e666c6e5..0769b8814 100644
--- a/buildstream/plugins/elements/compose.py
+++ b/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
diff --git a/buildstream/plugins/elements/distutils.py b/buildstream/plugins/elements/distutils.py
index 948e08b62..30ba6892c 100644
--- a/buildstream/plugins/elements/distutils.py
+++ b/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
 
diff --git a/buildstream/plugins/elements/filter.py b/buildstream/plugins/elements/filter.py
index 8ce16ff9f..ee9143ba7 100644
--- a/buildstream/plugins/elements/filter.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/import.py b/buildstream/plugins/elements/import.py
index 747455d70..c19a8bc36 100644
--- a/buildstream/plugins/elements/import.py
+++ b/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
diff --git a/buildstream/plugins/elements/junction.py b/buildstream/plugins/elements/junction.py
index 81fd57445..512c862ff 100644
--- a/buildstream/plugins/elements/junction.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/make.py b/buildstream/plugins/elements/make.py
index 37024926c..d8dff4c41 100644
--- a/buildstream/plugins/elements/make.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/makemaker.py b/buildstream/plugins/elements/makemaker.py
index 94d459f93..eb4d96930 100644
--- a/buildstream/plugins/elements/makemaker.py
+++ b/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
 
diff --git a/buildstream/plugins/elements/manual.py b/buildstream/plugins/elements/manual.py
index 998394b05..dbb799fb4 100644
--- a/buildstream/plugins/elements/manual.py
+++ b/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>`
 
diff --git a/buildstream/plugins/elements/meson.py b/buildstream/plugins/elements/meson.py
index 2b7b7831a..228e90ad1 100644
--- a/buildstream/plugins/elements/meson.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/modulebuild.py b/buildstream/plugins/elements/modulebuild.py
index c790cafb3..897430bae 100644
--- a/buildstream/plugins/elements/modulebuild.py
+++ b/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
 
diff --git a/buildstream/plugins/elements/pip.py b/buildstream/plugins/elements/pip.py
index b979a6d21..e2f33b207 100644
--- a/buildstream/plugins/elements/pip.py
+++ b/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
 
diff --git a/buildstream/plugins/elements/qmake.py b/buildstream/plugins/elements/qmake.py
index ab5843d8b..b0cd3f178 100644
--- a/buildstream/plugins/elements/qmake.py
+++ b/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
 
diff --git a/buildstream/plugins/elements/script.py b/buildstream/plugins/elements/script.py
index 6778b3fac..fbc15bd78 100644
--- a/buildstream/plugins/elements/script.py
+++ b/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.
 
diff --git a/buildstream/plugins/elements/stack.py b/buildstream/plugins/elements/stack.py
index 45c49c514..f6903c933 100644
--- a/buildstream/plugins/elements/stack.py
+++ b/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.
 """