From 26738f8451ce56379f7c850ee6b2f61f36730a4e Mon Sep 17 00:00:00 2001 From: Thanh Ha Date: Mon, 19 Mar 2018 18:20:51 -0400 Subject: [PATCH] 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 --- docs/best-practices.rst | 10 ++++++---- docs/gerrit.rst | 13 ++++++++----- docs/gpg.rst | 2 +- docs/infra/jenkins.rst | 2 +- docs/jenkins.rst | 11 ++++++++--- docs/project-bootstrap.rst | 12 ++++++++---- tox.ini | 2 +- 7 files changed, 33 insertions(+), 19 deletions(-) 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 -- 2.16.6