Add linkcheck for RST

Check RST files for valid links.

This is a separte target for now to evaluate how useful it is.
Whitelist build.opensuse.org URL for user-guide.
Remove also checklang from default tox invocation since it's not needed
to run by default.

Change-Id: I6c275518b9e55ab3b6bcea52894ea851924bee94

doc/user-guide/source/conf.py

@@ -209,6 +209,9 @@ htmlhelp_basename = 'user-guide'
 # If true, publish source files
 # html_copy_source = True
 
+# -- Options for linkcheck ------------------------------------------------
+linkcheck_ignore = [r'https://build.opensuse.org']
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {

tools/build-all-rst.sh

@@ -4,9 +4,16 @@ mkdir -p publish-docs
 
 GLOSSARY="--glossary"
 
+LINKCHECK=""
+if [[ $# > 0 ]] ; then
+    if [ "$1" = "--linkcheck" ] ; then
+        LINKCHECK="$1"
+    fi
+fi
+
 for guide in user-guide user-guide-admin networking-guide admin-guide-cloud; do
     tools/build-rst.sh doc/$guide $GLOSSARY --build build \
-        --target $guide
+        --target $guide $LINKCHECK
     # Build it only the first time
     GLOSSARY=""
 done
@@ -14,7 +21,7 @@ done
 # Draft guides
 for guide in contributor-guide; do
     tools/build-rst.sh doc/$guide --build build \
-        --target "draft/$guide"
+        --target "draft/$guide" $LINKCHECK
 done
 
-tools/build-install-guides-rst.sh
+tools/build-install-guides-rst.sh $LINKCHECK

tools/build-install-guides-rst.sh

@@ -2,6 +2,13 @@
 
 mkdir -p publish-docs
 
+LINKCHECK=""
+if [[ $# > 0 ]] ; then
+    if [ "$1" = "--linkcheck" ] ; then
+        LINKCHECK="$1"
+    fi
+fi
+
 title_org=$(grep "title::" doc/install-guide/source/index.rst | \
               awk '{print substr($0, index($0, "::")+3)}')
 
@@ -19,5 +26,6 @@ for tag in obs rdo ubuntu debian; do
     sed -i -e "s/\.\. title::.*/.. title:: ${title}/" \
       doc/install-guide/source/index.rst
     tools/build-rst.sh doc/install-guide  \
-        $GLOSSARY --tag ${tag} --target "draft/install-guide-${tag}"
+        $GLOSSARY --tag ${tag} --target "draft/install-guide-${tag}" \
+        $LINKCHECK
 done

tools/build-rst.sh

@@ -21,6 +21,7 @@ if [ -z "$DIRECTORY" ] ; then
     echo "--tag TAG: Use given tag for building"
     echo "--target TARGET: Copy files to publish-docs/$TARGET"
     echo "--build BUILD: Name of build directory"
+    echo "--linkcheck: Check validity of links instead of building"
     exit 1
 fi
 
@@ -29,10 +30,18 @@ TARGET=""
 TAG=""
 TAG_OPT=""
 BUILD=""
+LINKCHECK=""
 
-while [[ $# > 1 ]] ; do
+while [[ $# > 0 ]] ; do
     option="$1"
     case $option in
+        --build)
+            BUILD="$2"
+            shift
+            ;;
+        --linkcheck)
+            LINKCHECK=1
+            ;;
         --glossary)
             GLOSSARY=1
             ;;
@@ -45,10 +54,6 @@ while [[ $# > 1 ]] ; do
             TARGET="$2"
             shift
             ;;
-        --build)
-            BUILD="$2"
-            shift
-            ;;
     esac
     shift
 done
@@ -70,17 +75,25 @@ else
 fi
 
 if [ -z "$TAG" ] ; then
-    echo "Building $DIRECTORY"
+    echo "Checking $DIRECTORY..."
 else
-    echo "Building $DIRECTORY with tag $TAG"
+    echo "Checking $DIRECTORY with tag $TAG..."
 fi
-# Show sphinx-build invocation for easy reproduction
-set -x
-sphinx-build -E -W -b html $TAG_OPT $DIRECTORY/source $BUILD_DIR
-set +x
 
-# Copy RST
-if [ "$TARGET" != "" ] ; then
-    mkdir -p publish-docs/$TARGET
-    rsync -a $BUILD_DIR/ publish-docs/$TARGET/
+if [ "$LINKCHECK" = "1" ] ; then
+    # Show sphinx-build invocation for easy reproduction
+    set -x
+    sphinx-build -E -W -b linkcheck $TAG_OPT $DIRECTORY/source $BUILD_DIR
+    set +x
+else
+    # Show sphinx-build invocation for easy reproduction
+    set -x
+    sphinx-build -E -W -b html $TAG_OPT $DIRECTORY/source $BUILD_DIR
+    set +x
+
+    # Copy RST
+    if [ "$TARGET" != "" ] ; then
+        mkdir -p publish-docs/$TARGET
+        rsync -a $BUILD_DIR/ publish-docs/$TARGET/
+    fi
 fi

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 1.6
-envlist = checkniceness,checksyntax,checkdeletions,checkbuild,checklang,checklinks
+envlist = checkniceness,checksyntax,checkdeletions,checkbuild,checklinks
 skipsdist = True
 
 [testenv]
@@ -21,6 +21,10 @@ commands = {posargs}
 [testenv:checklinks]
 commands = openstack-doc-test --check-links {posargs}
 
+[testenv:linkcheck]
+commands =
+  {toxinidir}/tools/build-all-rst.sh --linkcheck
+
 [testenv:checkniceness]
 commands =
   openstack-doc-test --check-niceness {posargs}