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.

3 files changed, 35 insertions, 41 deletions

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@@