From 82731ddab08b6d8e09daf754fa552a072a44b394 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Wed, 28 Sep 2016 05:00:34 +0900 Subject: [PATCH] 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 | 2 +- doc/upstream-training/git.rst | 4 ++-- doc/upstream-training/index.rst | 17 +++++++++++++++-- tox.ini | 10 +++++----- 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/doc/upstream-training/conf.py b/doc/upstream-training/conf.py index c971e3de..feb22206 100644 --- a/doc/upstream-training/conf.py +++ b/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. diff --git a/doc/upstream-training/git.rst b/doc/upstream-training/git.rst index 439ca74a..41e61f01 100644 --- a/doc/upstream-training/git.rst +++ b/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 `__ so that they can be reviewed. Installation ------------ diff --git a/doc/upstream-training/index.rst b/doc/upstream-training/index.rst index e8d5bc5c..31bd4737 100644 --- a/doc/upstream-training/index.rst +++ b/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 -`_ +`Complete index in slide format only `_ diff --git a/tox.ini b/tox.ini index 48deb843..b57adf40 100644 --- a/tox.ini +++ b/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 =