From fc6e9a71d80aaed4a804c4922cc2094b9e6d1857 Mon Sep 17 00:00:00 2001
From: Boden R <bodenvmw@gmail.com>
Date: Tue, 19 Sep 2017 10:37:29 -0600
Subject: [PATCH] add doc link validation to release checklist and tox

This patch updates our doc conf.py to support the linkcheck builder in
addition to adding a new 'linkcheck' target in tox to run the builder.
Also the release checklist is updated suggesting the linkcheck tox
target be run prior to a release.

Change-Id: Ia7c282b7331f0b624bb3324f27dfec223cf414f7
Closes-Bug: #1716005
---
 doc/source/conf.py                                   | 12 ++++++++++++
 .../contributor/policies/release-checklist.rst       |  2 ++
 tox.ini                                              |  3 +++
 3 files changed, 17 insertions(+)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 223f2768d06..05bb1b87044 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -30,6 +30,11 @@ import logging
 import os
 import sys
 
+import eventlet
+
+# module ref generation can cause partial greening resulting in thread issues
+# during the linkcheck builder, so initialize eventlet upfront
+eventlet.monkey_patch()
 
 # NOTE(amotoki): In case of oslo_config.sphinxext is enabled,
 # when resolving automodule neutron.tests.functional.db.test_migrations,
@@ -271,3 +276,10 @@ config_generator_config_file = [
     _get_config_generator_config_definition(conf)
     for conf in _config_generator_config_files
 ]
+
+linkcheck_anchors_ignore = [
+    # skip gerrit anchors
+    '\/q\/.*',
+    'q\,.*',
+    '\/c\/.*'
+]
diff --git a/doc/source/contributor/policies/release-checklist.rst b/doc/source/contributor/policies/release-checklist.rst
index df646a82f54..f0b574569b6 100644
--- a/doc/source/contributor/policies/release-checklist.rst
+++ b/doc/source/contributor/policies/release-checklist.rst
@@ -33,6 +33,8 @@ Prior to major release,
    the context of the release planned;
 #. check that release notes and sample configuration files render correctly,
    arrange clean-up if needed.
+#. ensure all doc links are valid by running ``tox -e linkcheck`` and
+   addressing any broken links.
 
 New major release process contains several phases:
 
diff --git a/tox.ini b/tox.ini
index 362036c8d20..911b19cdb4a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -125,6 +125,9 @@ commands = {posargs}
 [testenv:docs]
 commands = sphinx-build -W -b html doc/source doc/build/html
 
+[testenv:linkcheck]
+commands = sphinx-build -W -b linkcheck doc/source doc/build/linkcheck
+
 [flake8]
 # E125 continuation line does not distinguish itself from next logical line
 # E126 continuation line over-indented for hanging indent