Add flag to fail with warnings in instructions

This is good practice so let's make sure our instructions set this
by default with a note in case a project is not ready for such a
configuration.

Change-Id: Ia71ca45af4e219c3eb50667772addbf77a584a82
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/docs/install.rst b/docs/install.rst
index ec8dc17..2a7ed92 100644 (file)
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -85,18 +85,27 @@ Follow these steps to install lfdocs-conf:
      [testenv:docs]
      deps = -rrequirements.txt
      commands =
-         sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+         sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
          echo "Generated docs available in {toxinidir}/docs/_build/html"
      whitelist_externals = echo
 
      [testenv:docs-linkcheck]
          deps = -rrequirements.txt
-         commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
+         commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
 
    This will configure 2 tox testenvs. The first to generate the docs and the
    2nd to verify links inside of the documentation. The 2nd one is useful to
    ensure the documentation does not contain any broken links.
 
+   .. note::
+
+      The ``-W`` flag enables an option to fail the build even on warnings.
+      This flag catches useful issues with docs and projects should strive
+      to have their docs passing with this enabled. If setting up an existing
+      project that has warnings that are unable to resolve now then
+      remove this option temporarily, until such a time that the project can
+      clean up the docs.
+
 #. To test run::
 
      tox -e docs