Use HTMLProofer to validate documentation links (#3737) (#3740)

use HTMLProofer to validate documentation links
also fix a couple links

(cherry picked from commit 6bbaa5d)

.travis.yml

@@ -84,6 +84,10 @@ jobs:
   - stage: build
     script: ./ci/build.sh
     name: "Build CAS"
+  - stage: build
+    script: ./ci/html-proofer-docs.sh
+    if: branch =~ /^\d+\.\d+\.x$/ or branch = master
+    name: "Validate Documentation"
     ############################################
   - stage: publish
     if: NOT commit_message =~ ^\[skip\s+snapshots\] and type != "pull_request" and (branch =~ /^\d+\.\d+\.x$/ or branch = master)

ci/html-proofer-docs.rb

@@ -0,0 +1,39 @@
+require 'html-proofer'
+require 'html/pipeline'
+require 'find'
+require 'fileutils'
+
+# make an out dir
+Dir.mkdir("out") unless File.exist?("out")
+
+pipeline = HTML::Pipeline.new [
+  HTML::Pipeline::MarkdownFilter,
+  HTML::Pipeline::TableOfContentsFilter
+], :gfm => true
+
+# iterate over files, and generate HTML from Markdown
+Find.find("./docs") do |path|
+  if File.extname(path) == ".md"
+    contents = File.read(path)
+    result = pipeline.call(contents)
+    dirname = File.dirname(path)
+    FileUtils.mkdir_p ("out/" + dirname)
+    content_str = result[:output].to_s
+    filename = path.split("/").pop.sub('.md', '.html')
+    if filename == "sidebar.html"
+      content_str = content_str.gsub! '/%24version' '.'
+    end
+    File.open("out/#{dirname}/#{filename}", 'w') { |file| file.write(content_str) }
+  end
+end
+# url_ignore - ignore links content not in branch
+# file_ignore - ignore CAS spec b/c it has lots of bad anchor links, only *.html files are processed
+options = {
+            :file_ignore =>  [ %r{.*/CAS-Protocol-Specification.html} ],
+            :disable_external => true,
+            :only_4xx => true,
+            :empty_alt_ignore => true,
+            :url_ignore => [ %r{^/cas}, %r{^../images/}, %r{^../../developer/} ],
+          }
+# test your out dir!
+HTMLProofer.check_directory("./out", options).run

ci/html-proofer-docs.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+source ./ci/functions.sh
+
+runBuild=false
+echo "Reviewing changes that might affect the Gradle build..."
+currentChangeSetAffectsDocumentation
+retval=$?
+if [ "$retval" == 0 ]
+then
+    echo "Found changes that affect project documentation."
+    runBuild=true
+else
+    echo "Changes do NOT affect project documentation."
+    runBuild=false
+fi
+
+if [ "$runBuild" = false ]; then
+    exit 0
+fi
+
+HTML_PROOFER_IMAGE=hdeadman/html-proofer:latest
+DOCS_FOLDER=$(pwd)/docs/cas-server-documentation
+DOCS_OUTPUT=$(pwd)/docs/cas-server-documentation/build/out
+HTML_PROOFER_SCRIPT=$(pwd)/ci/html-proofer-docs.rb
+
+echo "Running html-proof image: ${HTML_PROOFER_IMAGE}"
+docker run --name="html-proofer" --rm \
+    --workdir /root \
+    -v ${DOCS_FOLDER}:/root/docs \
+    -v ${DOCS_OUTPUT}:/root/out \
+    -v ${HTML_PROOFER_SCRIPT}:/root/html-proofer-docs.rb \
+    --entrypoint /usr/local/bin/ruby \
+     ${HTML_PROOFER_IMAGE} \
+     /root/html-proofer-docs.rb
+retVal=$?
+if [[ ${retVal} -eq 0 ]]; then
+    echo "HTML Proofer found no bad links."
+    exit 0
+else
+    echo "HTML Proofer found bad links."
+    exit ${retVal}
+fi

docs/cas-server-documentation/configuration/Configuration-Properties.md

@@ -3725,7 +3725,7 @@ Signing & encryption settings for this registry are available [here](Configurati
 
 ### CouchDb Ticket Registry
 
-To learn more about this topic, [please review this guide](../ticketing/CouchDb-Ticket-Registry.html). Database settings for this feature are available [here](Configuration-Properties-Common.html#couchdb-integration-settings) under the configuration key `cas.ticket.registry.couchdb`.
+To learn more about this topic, [please review this guide](../ticketing/CouchDb-Ticket-Registry.html). Database settings for this feature are available [here](Configuration-Properties-Common.html#couchdb-configuration) under the configuration key `cas.ticket.registry.couchdb`.
 
 ### Couchbase Ticket Registry
 

docs/cas-server-documentation/planning/Security-Guide.md

@@ -75,7 +75,8 @@ the principal of an SSO session since the user must verify his or her credential
 Forced authentication is suitable for services where higher security is desired or mandated. Typically forced
 authentication is configured on a per-service basis, but the [service management](#service-management) facility
 provides some support for implementing forced authentication as a matter of centralized security policy.
-Forced authentication may be combined with [multi-factor authentication](#multifactor-authentication) features to
+Forced authentication may be combined with 
+[multi-factor authentication](../configuration/Configuration-Properties.html#multifactor-authentication) features to
 implement arbitrary service-specific access control policy.