Fix warnings of upstream training HTML pages

Most warnings are "document isn't included in any toctree".
This is because documents are not listed in any toctree.
In the upstream training document, explicit toctree looks unnecessary,
so this commit adds a hidden toctree to cover all unlisted documents.
It makes these documents reachable from standard navigation (prev/next).

doc/upstream-training/README.rst is not intended to link from the document.
Add README.rst to exclude_patterns in conf.py.

Also specifies sphinx-build -W option to detect warnings.

Change-Id: I42750cde20a35342dce7857e275f7fa27211236b

doc/upstream-training/conf.py

@@ -84,7 +84,7 @@ html_context = {"gitsha": gitsha, "bug_tag": bug_tag,
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['source', 'build']
+exclude_patterns = ['source', 'build', 'README.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

doc/upstream-training/git.rst

@@ -74,8 +74,8 @@ sub-command to git like so::
   git review
 
 When you have changes in an OpenStack project repository, you can use this
-sub-command to have the changes posted to :doc:`gerrit` so that they can be
-reviewed.
+sub-command to have the changes posted to
+`Gerrit <https://review.openstack.org/>`__ so that they can be reviewed.
 
 Installation
 ------------

doc/upstream-training/index.rst

@@ -2,6 +2,20 @@
 OpenStack Upstream Training
 ===========================
 
+.. All documents in the source directory must occur in some toctree directive.
+   Otherwise Sphinx will emit a warning if it finds a file that is not
+   included. Documents which belong to no toctree should be added to the
+   hidden toctree below.
+
+.. toctree::
+   :hidden:
+
+   upstream-details
+   irc
+   accounts
+   git
+   upstream-archives
+
 Abstract
 ========
 
@@ -121,5 +135,4 @@ The Contribution Process
 * `Lego applied to Free Software contributions
   <21-training-agile-for-contributors.html>`_
 
-`Complete index in slide format only
-<http://docs.openstack.org/upstream-training/slide-index.html>`_
+`Complete index in slide format only <slide-index.html>`_

tox.ini

@@ -31,7 +31,7 @@ commands =
   # Build upstream-training slides
   sphinx-build -W -b slides -d doc/upstream-training/build/slides.doctrees doc/upstream-training/source/ doc/upstream-training/build/slides
   # Build upstream landing page
-  sphinx-build -b html -d doc/upstream-training/build/slides.doctrees doc/upstream-training doc/upstream-training/build/slides
+  sphinx-build -W -b html -d doc/upstream-training/build/slides.doctrees doc/upstream-training doc/upstream-training/build/slides
   # Build training-guides slides
   sphinx-build -b slides -d doc/training-guides/build/slides.doctrees/associate-guide  doc/training-guides/associate-guide/ doc/training-guides/build/slides/associate-guide
   # Build training-guides landing page
@@ -46,9 +46,9 @@ commands =
 passenv = ZUUL*
 commands =
   # Build upstream-training slides
-  sphinx-build -b slides -d doc/upstream-training/build/slides.doctrees/ doc/upstream-training/source/ doc/upstream-training/build/slides
+  sphinx-build -W -b slides -d doc/upstream-training/build/slides.doctrees/ doc/upstream-training/source/ doc/upstream-training/build/slides
   # Build upstream landing page
-  sphinx-build -b html -d doc/upstream-training/build/slides.doctrees/ doc/upstream-training doc/upstream-training/build/slides
+  sphinx-build -W -b html -d doc/upstream-training/build/slides.doctrees/ doc/upstream-training doc/upstream-training/build/slides
   # Build training-guides slides
   sphinx-build -b slides -d doc/training-guides/build/slides.doctrees/associate-guide doc/training-guides/associate-guide/ doc/training-guides/build/slides/associate-guide
   # Build training-guides landing page
@@ -69,9 +69,9 @@ commands =
   # Niceness test
   doc8 doc/upstream-training
   # Build upstream-training slides
-  sphinx-build -b slides doc/upstream-training/source/ doc/upstream-training/build/slides
+  sphinx-build -W -b slides doc/upstream-training/source/ doc/upstream-training/build/slides
   # Build upstream landing page index.html
-  sphinx-build -b html doc/upstream-training doc/upstream-training/build/slides
+  sphinx-build -W -b html doc/upstream-training doc/upstream-training/build/slides
 
 [testenv:training-slides]
 commands =