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.

27 files changed, 108 insertions, 81 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.
 """
diff --git a/buildstream/plugins/sources/bzr.py b/buildstream/plugins/sources/bzr.py
index 3732304fb..b499d49d3 100644
--- a/buildstream/plugins/sources/bzr.py
+++ b/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:**
 
diff --git a/buildstream/plugins/sources/deb.py b/buildstream/plugins/sources/deb.py
index daf6f94c7..4948d1933 100644
--- a/buildstream/plugins/sources/deb.py
+++ b/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:**
 
diff --git a/buildstream/plugins/sources/git.py b/buildstream/plugins/sources/git.py
index f178656b0..44065ad8f 100644
--- a/buildstream/plugins/sources/git.py
+++ b/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:**
 
diff --git a/buildstream/plugins/sources/local.py b/buildstream/plugins/sources/local.py
index 3193d101d..673add1bf 100644
--- a/buildstream/plugins/sources/local.py
+++ b/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:**
 
diff --git a/buildstream/plugins/sources/ostree.py b/buildstream/plugins/sources/ostree.py
index b311e24bf..c77b3a77f 100644
--- a/buildstream/plugins/sources/ostree.py
+++ b/buildstream/plugins/sources/ostree.py
@@ -18,7 +18,9 @@
 #  Authors:
 #        Andrew Leeming <andrew.leeming@codethink.co.uk>
 
-"""A Source implementation for importing/staging of OSTree checkouts.
+"""
+ostree - stage files from an OSTree repository
+==============================================
 
 **Usage:**
 
diff --git a/buildstream/plugins/sources/patch.py b/buildstream/plugins/sources/patch.py
index c9e40b1e6..88fb2d59c 100644
--- a/buildstream/plugins/sources/patch.py
+++ b/buildstream/plugins/sources/patch.py
@@ -18,7 +18,9 @@
 #  Authors:
 #        Chandan Singh <csingh43@bloomberg.net>
 
-"""A Source implementation for applying local patches
+"""
+patch - apply locally stored patches
+====================================
 
 **Usage:**
 
diff --git a/buildstream/plugins/sources/tar.py b/buildstream/plugins/sources/tar.py
index e41824505..324006b21 100644
--- a/buildstream/plugins/sources/tar.py
+++ b/buildstream/plugins/sources/tar.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+#
 #  Copyright (C) 2017 Codethink Limited
 #
 #  This program is free software; you can redistribute it and/or
@@ -17,7 +18,9 @@
 #  Authors:
 #        Jonathan Maw <jonathan.maw@codethink.co.uk>
 
-"""A source implementation for staging tar files
+"""
+tar - stage files from tar archives
+===================================
 
 **Usage:**
 
diff --git a/buildstream/plugins/sources/zip.py b/buildstream/plugins/sources/zip.py
index fdf8947ec..f167c3e63 100644
--- a/buildstream/plugins/sources/zip.py
+++ b/buildstream/plugins/sources/zip.py
@@ -18,7 +18,9 @@
 #  Authors:
 #        Mathieu Bridon <bochecha@daitauha.fr>
 
-"""A source implementation for staging zip files
+"""
+zip - stage files from zip archives
+===================================
 
 **Usage:**
 
diff --git a/doc/Makefile b/doc/Makefile
index c894a135e..9cc3f488b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -43,13 +43,12 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 #   from plugin documentation.
 #
 define plugin-doc-skeleton
-	@for file in $$(find ${1} -name "*.py" ! -name "__init__.py"); do \
+	@for file in $$(find ${1} -name "*.py" ! -name "_*.py"); do	\
 	    base=$$(basename $$file);					\
 	    module=${2}.$${base%.py};					\
 	    modname=$${base%.py};					\
 	    echo -n "Generating source/${2}/$${modname}.rst... ";	\
-	    sed -e "s|@@MODULENAME@@|$${modname}|g" 			\
-	        -e "s|@@MODULE@@|$${module}|g" 				\
+	    sed -e "s|@@MODULE@@|$${module}|g" 				\
 		source/plugin.rsttemplate > 				\
                 source/${2}/$${modname}.rst.tmp && 			\
 		mv source/${2}/$${modname}.rst.tmp source/${2}/$${modname}.rst || exit 1; \
diff --git a/doc/source/authoring.rst b/doc/source/authoring.rst
index 90866c6e6..dc3c2281f 100644
--- a/doc/source/authoring.rst
+++ b/doc/source/authoring.rst
@@ -28,49 +28,49 @@ given element specify their plugin specific configuration directly
 :ref:`in their source declarations <format_sources>`.
 
 
-Elements
-~~~~~~~~
-The following element types are provided with BuildStream:
-
-
 General elements
-''''''''''''''''
+~~~~~~~~~~~~~~~~
+.. toctree::
+   :maxdepth: 1
 
-* :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
-* :mod:`junction <elements.junction>` - Integrate subprojects
-* :mod:`filter <elements.filter>` - Extract a subset of files from another element
+   elements/stack
+   elements/import
+   elements/compose
+   elements/script
+   elements/junction
+   elements/filter
 
 
 Build elements
-''''''''''''''
+~~~~~~~~~~~~~~
+.. toctree::
+   :maxdepth: 1
 
-* :mod:`manual <elements.manual>` - Manual Build Element
-* :mod:`make <elements.make>` - Make Build Element
-* :mod:`autotools <elements.autotools>` - Autotools Build Element
-* :mod:`cmake <elements.cmake>` - CMake Build Element
-* :mod:`qmake <elements.qmake>` - QMake Build Element
-* :mod:`distutils <elements.distutils>` - Python Distutils Build Element
-* :mod:`makemaker <elements.makemaker>` - Perl MakeMaker Build Element
-* :mod:`modulebuild <elements.modulebuild>` - Perl Module::Build Build Element
-* :mod:`meson <elements.meson>` - Meson Build Element
-* :mod:`pip <elements.pip>` - Pip build element
+   elements/manual
+   elements/make
+   elements/autotools
+   elements/cmake
+   elements/qmake
+   elements/distutils
+   elements/makemaker
+   elements/modulebuild
+   elements/meson
+   elements/pip
 
 
 Sources
 ~~~~~~~
-The following source types are provided with BuildStream:
-
-* :mod:`local <sources.local>` - A Source implementation for local files and directories
-* :mod:`tar <sources.tar>` - A Source implementation for tarballs
-* :mod:`zip <sources.zip>` - A Source implementation for zip archives
-* :mod:`git <sources.git>` - A Source implementation for git
-* :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
-* :mod:`deb <sources.deb>` - A Source implementation for deb packages
+.. toctree::
+   :maxdepth: 1
+
+   sources/local
+   sources/tar
+   sources/zip
+   sources/git
+   sources/bzr
+   sources/ostree
+   sources/patch
+   sources/deb
 
 
 External plugins
diff --git a/doc/source/plugin.rsttemplate b/doc/source/plugin.rsttemplate
index 4b252b647..d6ee9488f 100644
--- a/doc/source/plugin.rsttemplate
+++ b/doc/source/plugin.rsttemplate
@@ -1,6 +1 @@
-:orphan:
-
-@@MODULENAME@@ plugin
-============================================
-
 .. automodule:: @@MODULE@@