Fail build on Sphinx warnings

Resolve Sphinx warnings and enable flag to fail the build on
warnings. Sphinx has many warnings that should be treated as
real issues so is a useful flag to set.

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

diff --git a/docs/best-practices.rst b/docs/best-practices.rst
index 1536440..3fca638 100644 (file)
--- a/docs/best-practices.rst
+++ b/docs/best-practices.rst
@@ -43,11 +43,10 @@ that they are not hitting any of these):
 - Does the code cause backwards compatibility breakage?
   (If so it needs documentation)
 
-Google posted an interesting blog on effective code review and how to spend both
-your own and your reviewers' time effectively.
+Google posted an interesting blog (`google-blog-code-health`_) on effective
+code review and how to spend both your own and your reviewers' time
+effectively.
 
-.. noqa
-https://testing.googleblog.com/2017/06/code-health-too-many-comments-on-your.html
 
 
 Coala (Generic Linting)
@@ -133,3 +132,6 @@ Jenkins Job Builder
 ===================
 
 :ref:`Jenkins Job Builder Best Practices <global-jjb-best-practices>`
+
+.. noqa
+.. _google-blog-code-health: https://testing.googleblog.com/2017/06/code-health-too-many-comments-on-your.html

diff --git a/docs/gerrit.rst b/docs/gerrit.rst
index e25f38a..9f839fc 100644 (file)
--- a/docs/gerrit.rst
+++ b/docs/gerrit.rst
@@ -228,8 +228,8 @@ if possible as it makes working with Gerrit much easier.
 #. Install ``git-review`` via your local package management system
 
    If your distro does not package git-review or you need a newer version.
-   Install it via PyPi in a
-   :ref:`virtualenv <https://virtualenv.pypa.io/en/stable/>`_ environment:
+
+   Install it via PyPi in a virtualenv_ environment:
 
    .. code-block:: bash
 
@@ -277,7 +277,7 @@ This method is a useful fallback in situations where we cannot use
    way of making an update to an exisiting gerrit. In such case, is best to let gerrit handle
    this via Change-Id in the commit text.
 
-   More options for this command: `git-push https://git-scm.com/docs/git-push`_.
+   More options for this command: `git-push <https://git-scm.com/docs/git-push>`_.
 
 Once pushed we should see some output in the terminal as described in
 :ref:`Gerrit Push Output <gerrit-push-output>`.
@@ -320,7 +320,7 @@ Gerrit Code Review.
 
 #. Rebase the patch before you start working on it
 
-   .. code-block::
+   .. code-block:: bash
 
       git pull --rebase
 
@@ -349,7 +349,7 @@ Gerrit Code Review.
 
 #. Rebase the patch one last time
 
-   .. code-block::
+   .. code-block:: bash
 
       git pull --rebase
 
@@ -844,3 +844,6 @@ methods to configure topics:
    Both methods achieve the same result so is up to preference. Further
    documentation available at `Gerrit Topics
    <https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics>`_.
+
+
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/

diff --git a/docs/gpg.rst b/docs/gpg.rst
index 5e2369f..f3e4a42 100644 (file)
--- a/docs/gpg.rst
+++ b/docs/gpg.rst
@@ -118,7 +118,7 @@ Generate the GPG keys
 
           gpg --export -a <KEYID-FINGERPRINT>
 
-   b. Open the project's `Gerrit <https://git.opendaylight.org`_ and go to
+   b. Open the project's `Gerrit <https://git.opendaylight.org>`_ and go to
       project settings and gpg-keys.
    c. Click the `Add Key` button.
    d. Copy the output from the above command, paste it into the box, and click

diff --git a/docs/infra/jenkins.rst b/docs/infra/jenkins.rst
index e64c552..8c63905 100644 (file)
--- a/docs/infra/jenkins.rst
+++ b/docs/infra/jenkins.rst
@@ -1,4 +1,4 @@
-.. _lfreleng-docs-jenkins:
+.. _jenkins-infra:
 
 #######
 Jenkins

diff --git a/docs/jenkins.rst b/docs/jenkins.rst
index 5c4c83d..1bb02cc 100644 (file)
--- a/docs/jenkins.rst
+++ b/docs/jenkins.rst
@@ -1,4 +1,4 @@
-.. _lfreleng-docs-jenkins:
+.. _jenkins-guide:
 
 #############
 Jenkins Guide
@@ -292,6 +292,8 @@ To work on existing jobs or create new jobs, navigate to the `/jjb` directory
 where you will find all job templates for the project.  Follow the below commands
 to test, push or delete jobs in your Sandbox environment.
 
+.. _verify-jjb:
+
 Verify JJB
 ^^^^^^^^^^
 
@@ -323,6 +325,8 @@ Execute the following command to pipe-out to a directory:
 
 The output directory will contain files with the XML configurations.
 
+.. _push-job:
+
 Push a Job
 ^^^^^^^^^^
 
@@ -367,8 +371,9 @@ Click the Apply or Save (to save and exit the configuration) buttons to save the
 This is useful in the case where you might want to test quick tweaks to a job before
 modifying the YAML.
 
-Edit the job in your terminal and follow the described steps in `To Test a Job`_
-and `To Push a Job`_ to push any changes and have them ready to push to Gerrit.
+Edit the job in your terminal and follow the described steps in
+:ref:`Verify JJB <verify-jjb>` and `Push Job <push-job>`
+to push any changes and have them ready to push to Gerrit.
 
 .. important::
 

diff --git a/docs/project-bootstrap.rst b/docs/project-bootstrap.rst
index 0c49a40..3351150 100644 (file)
--- a/docs/project-bootstrap.rst
+++ b/docs/project-bootstrap.rst
@@ -35,13 +35,17 @@ Steps
 #. Git commit the current files and push to Gerrit
 #. Confirm verify jobs work
 #. Merge the patch and confirm merge job works
-#. Install lf-ansible to GIT_ROOT/lf-ansible::
+#. Install lf-ansible to GIT_ROOT/lf-ansible
 
-   git submodule add https://github.com/lfit/releng-lf-ansible.git lf-ansible
+   .. code-block:: bash
 
-#. Install common-packer to GIT_ROOT/packer/common-packer::
+      git submodule add https://github.com/lfit/releng-lf-ansible.git lf-ansible
 
-   git submodule add https://github.com/lfit/releng-common-packer.git packer/common-packer
+#. Install common-packer to GIT_ROOT/packer/common-packer
+
+   .. code-block:: bash
+
+      git submodule add https://github.com/lfit/releng-common-packer.git packer/common-packer
 
 #. Git commit and merge patch in Gerrit
 #. Create Initial CI Packer job in jjb/ci-management/ci-packer.yaml

diff --git a/tox.ini b/tox.ini
index be16247..37194c3 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -21,7 +21,7 @@ commands =
 [testenv:docs]
 deps = -rrequirements.txt
 commands =
-    sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+    sphinx-build -b html -n -W -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
     echo "Generated docs available in {toxinidir}/docs/_build/html"
 whitelist_externals = echo