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

@@ -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\/.*'
+]

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:
 

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