From 16e03eff4154bc894b5b2f8460314f2cf25f79f4 Mon Sep 17 00:00:00 2001 From: Thanh Ha Date: Mon, 30 Apr 2018 15:08:14 -0400 Subject: [PATCH] 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 --- docs/install.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index ec8dc17..2a7ed92 100644 --- 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 -- 2.16.6