Documentation: Fix warnings, and make all warnings errors.gating-on-docs-breakage

Some of the warnings from sphinx-build are really just warnings,
but a lot of the things we want to avoid and really break documentation,
like broken internal references and some invalid rst directives should
really be errors.

Now we treat all warnings as errors, this should ensure that
any commits landing upstream never break the docs.

16 files changed, 31 insertions, 2 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 6a10c488f..54a37a56e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -10,7 +10,7 @@ BUILDDIR      = build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
diff --git a/doc/source/artifacts.rst b/doc/source/artifacts.rst
index 330de818c..7a5d3c0e5 100644
--- a/doc/source/artifacts.rst
+++ b/doc/source/artifacts.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _artifacts:
 
 
diff --git a/doc/source/cachekeys.rst b/doc/source/cachekeys.rst
index da8d049c1..9336b7bc3 100644
--- a/doc/source/cachekeys.rst
+++ b/doc/source/cachekeys.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _cachekeys:
 
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f702ecd0f..418a99f5d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -158,7 +158,7 @@ html_theme = 'alabaster'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/doc/source/config.rst b/doc/source/config.rst
index 2b9883f93..a5ceb8762 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _config:
 
 
diff --git a/doc/source/docker.rst b/doc/source/docker.rst
index aee200ec8..e2639379c 100644
--- a/doc/source/docker.rst
+++ b/doc/source/docker.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _docker:
 
 BuildStream inside Docker
diff --git a/doc/source/format.rst b/doc/source/format.rst
index 7e4638e1c..6f6e2f0ec 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _format:
 
 Element Constructs
diff --git a/doc/source/formatintro.rst b/doc/source/formatintro.rst
index 4d7982fa2..6d1f234d5 100644
--- a/doc/source/formatintro.rst
+++ b/doc/source/formatintro.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _formatintro:
 
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e79d5aba..f45a9cd15 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -5,6 +5,9 @@
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
+
+   modules
 
 BuildStream Documentation
 =========================
diff --git a/doc/source/install.rst b/doc/source/install.rst
index e0fcb7088..ecd51b952 100644
--- a/doc/source/install.rst
+++ b/doc/source/install.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _installing:
 
 
diff --git a/doc/source/invoking.rst b/doc/source/invoking.rst
index ca14f24bd..1c995a1e7 100644
--- a/doc/source/invoking.rst
+++ b/doc/source/invoking.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _invoking:
 
 Invoking BuildStream
diff --git a/doc/source/plugin.rsttemplate b/doc/source/plugin.rsttemplate
index 11e090f8b..4b252b647 100644
--- a/doc/source/plugin.rsttemplate
+++ b/doc/source/plugin.rsttemplate
@@ -1,3 +1,5 @@
+:orphan:
+
 @@MODULENAME@@ plugin
 ============================================
 
diff --git a/doc/source/pluginauthoring.rst b/doc/source/pluginauthoring.rst
index ce22d3f32..c42bd575b 100644
--- a/doc/source/pluginauthoring.rst
+++ b/doc/source/pluginauthoring.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _pluginauthoring:
 
 
diff --git a/doc/source/pluginindex.rst b/doc/source/pluginindex.rst
index bcc20b5e9..57f14876d 100644
--- a/doc/source/pluginindex.rst
+++ b/doc/source/pluginindex.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _plugins:
 
 Plugins
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst
index e1649de54..c85d3818c 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/projectconf.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _projectconf:
 
 
diff --git a/doc/source/public.rst b/doc/source/public.rst
index eb7381ec6..7a0da8e63 100644
--- a/doc/source/public.rst
+++ b/doc/source/public.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _public: