From: Thanh Ha Date: Mon, 19 Mar 2018 22:20:51 +0000 (-0400) Subject: Fail build on Sphinx warnings X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=26738f8451ce56379f7c850ee6b2f61f36730a4e;p=releng%2Fdocs.git 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 --- diff --git a/docs/best-practices.rst b/docs/best-practices.rst index 1536440..3fca638 100644 --- 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 ` + +.. 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 --- 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 `_ 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 `_. Once pushed we should see some output in the terminal as described in :ref:`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 `_. + + +.. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/gpg.rst b/docs/gpg.rst index 5e2369f..f3e4a42 100644 --- a/docs/gpg.rst +++ b/docs/gpg.rst @@ -118,7 +118,7 @@ Generate the GPG keys gpg --export -a - b. Open the project's `Gerrit `_ 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 --- 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 --- 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 ` and `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 --- 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 --- 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