Documentation: Introduces a check stage to validate HTML and links

dduportal · traefiker · commit 3ef6bf2118cd · 2018-07-12T18:26:03.000+02:00
diff --git a/.travis.yml b/.travis.yml
@@ -16,6 +16,7 @@ env:
 
 script:
 - echo "Skipping tests... (Tests are executed on SemaphoreCI)"
+- if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then make docs-verify; fi
 
 before_deploy:
   - >
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -160,9 +160,11 @@ Integration tests must be run from the `integration/` directory and require the
 
 The [documentation site](http://docs.traefik.io/) is built with [mkdocs](http://mkdocs.org/)
 
-### Method 1: `Docker` and `make`
+### Building Documentation
 
-You can test documentation using the `docs` target.
+#### Method 1: `Docker` and `make`
+
+You can build the documentation and serve it locally with livereloading, using the `docs` target:
 
 ```bash
 $ make docs
@@ -177,11 +179,18 @@ docker run  --rm -v /home/user/go/github/containous/traefik:/mkdocs -p 8000:8000
 
 And go to [http://127.0.0.1:8000](http://127.0.0.1:8000).
 
-### Method 2: `mkdocs`
+If you only want to build the documentation without serving it locally, you can use the following command:
+
+```bash
+$ make docs-build
+...
+```
+
+#### Method 2: `mkdocs`
 
 First make sure you have python and pip installed
 
-```shell
+```bash
 $ python --version
 Python 2.7.2
 $ pip --version
@@ -190,22 +199,42 @@ pip 1.5.2
 
 Then install mkdocs with pip
 
-```shell
+```bash
 pip install --user -r requirements.txt
 ```
 
-To test documentation locally run `mkdocs serve` in the root directory, this should start a server locally to preview your changes.
+To build documentation locally and serve it locally,
+run `mkdocs serve` in the root directory,
+this should start a server locally to preview your changes.
 
-```shell
+```bash
 $ mkdocs serve
 INFO    -  Building documentation...
-WARNING -  Config value: 'theme'. Warning: The theme 'united' will be removed in an upcoming MkDocs release. See http://www.mkdocs.org/about/release-notes/ for more details
 INFO    -  Cleaning site directory
 [I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
 [I 160505 22:31:24 handlers:59] Start watching changes
 [I 160505 22:31:24 handlers:61] Start detecting changes
 ```
 
+### Verify Documentation
+
+You can verify that the documentation meets some expectations, as checking for dead links, html markup validity.
+
+```bash
+$ make docs-verify
+docker build -t traefik-docs-verify ./script/docs-verify-docker-image ## Build Validator image
+...
+docker run --rm -v /home/travis/build/containous/traefik:/app traefik-docs-verify ## Check for dead links and w3c compliance
+=== Checking HTML content...
+Running ["HtmlCheck", "ImageCheck", "ScriptCheck", "LinkCheck"] on /app/site/basics/index.html on *.html...
+```
+
+If you recently changed the documentation, do not forget to clean it to have it rebuilt:
+
+```bash
+$ make docs-clean docs-verify
+...
+```
 
 ## How to Write a Good Issue
 
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all
+.PHONY: all docs-verify docs docs-clean docs-build
 
 TRAEFIK_ENVS := \
 	-e OS_ARCH_ARG \
@@ -22,6 +22,7 @@ REPONAME := $(shell echo $(REPO) | tr '[:upper:]' '[:lower:]')
 TRAEFIK_IMAGE := $(if $(REPONAME),$(REPONAME),"containous/traefik")
 INTEGRATION_OPTS := $(if $(MAKE_DOCKER_HOST),-e "DOCKER_HOST=$(MAKE_DOCKER_HOST)", -e "TEST_CONTAINER=1" -v "/var/run/docker.sock:/var/run/docker.sock")
 TRAEFIK_DOC_IMAGE := traefik-docs
+TRAEFIK_DOC_VERIFY_IMAGE := $(TRAEFIK_DOC_IMAGE)-verify
 
 DOCKER_BUILD_ARGS := $(if $(DOCKER_VERSION), "--build-arg=DOCKER_VERSION=$(DOCKER_VERSION)",)
 DOCKER_RUN_OPTS := $(TRAEFIK_ENVS) $(TRAEFIK_MOUNT) "$(TRAEFIK_DEV_IMAGE)"
@@ -94,11 +95,23 @@ image-dirty: binary ## build a docker traefik image
 image: clear-static binary ## clean up static directory and build a docker traefik image
 	docker build -t $(TRAEFIK_IMAGE) .
 
+docs-image:
+	docker build -t $(TRAEFIK_DOC_IMAGE) -f docs.Dockerfile .
+
 docs: docs-image
 	docker run  $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOC_IMAGE) mkdocs serve
 
-docs-image:
-	docker build -t $(TRAEFIK_DOC_IMAGE) -f docs.Dockerfile .
+docs-build: site
+
+docs-verify: site
+	docker build -t $(TRAEFIK_DOC_VERIFY_IMAGE) ./script/docs-verify-docker-image ## Build Validator image
+	docker run --rm -v $(CURDIR):/app $(TRAEFIK_DOC_VERIFY_IMAGE) ## Check for dead links and w3c compliance
+
+site: docs-image
+	docker run  $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOC_IMAGE) mkdocs build
+
+docs-clean:
+	rm -rf $(CURDIR)/site
 
 clear-static:
 	rm -rf static
diff --git a/docs.Dockerfile b/docs.Dockerfile
@@ -1,11 +1,10 @@
-FROM alpine
+FROM alpine:3.7
 
 ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.local/bin
 
 COPY requirements.txt /mkdocs/
 WORKDIR /mkdocs
+VOLUME /mkdocs
 
-RUN apk --update upgrade \
-&& apk --no-cache --no-progress add py-pip \
-&& rm -rf /var/cache/apk/* \
-&& pip install --user -r requirements.txt
+RUN apk --no-cache --no-progress add py-pip \
+  && pip install --user -r requirements.txt
diff --git a/docs/configuration/acme.md b/docs/configuration/acme.md
@@ -371,7 +371,7 @@ For example, the rule `Host:test1.traefik.io,test2.traefik.io` will request a ce
 
 !!! warning
     `onHostRule` option can not be used to generate wildcard certificates.
-    Refer to [wildcard generation](/configuration/acme/#wildcard-domain) for further information.
+    Refer to [wildcard generation](/configuration/acme/#wildcard-domains) for further information.
 
 ### `storage`
 
diff --git a/docs/configuration/api.md b/docs/configuration/api.md
@@ -30,7 +30,7 @@
   debug = true
 ```
 
-For more customization, see [entry points](/configuration/entrypoints/) documentation and [examples](/user-guide/examples/#ping-health-check).
+For more customization, see [entry points](/configuration/entrypoints/) documentation and the examples below.
 
 ## Web UI
 
diff --git a/docs/index.md b/docs/index.md
@@ -3,7 +3,7 @@
 </p>
 
 [![Build Status SemaphoreCI](https://semaphoreci.com/api/v1/containous/traefik/branches/master/shields_badge.svg)](https://semaphoreci.com/containous/traefik)
-[![Docs](https://img.shields.io/badge/docs-current-brightgreen.svg)](https://docs.traefik.io)
+[![Docs](https://img.shields.io/badge/docs-current-brightgreen.svg)](/)
 [![Go Report Card](https://goreportcard.com/badge/github.com/containous/traefik)](https://goreportcard.com/report/github.com/containous/traefik)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/containous/traefik/blob/master/LICENSE.md)
 [![Join the chat at https://slack.traefik.io](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://slack.traefik.io)
diff --git a/docs/user-guide/cluster.md b/docs/user-guide/cluster.md
@@ -26,8 +26,8 @@ If this instance fails, another manager will be automatically elected.
 
 ## Træfik cluster and Let's Encrypt
 
-**In cluster mode, ACME certificates have to be stored in [a KV Store entry](/configuration/acme/#storage-kv-entry).**
+**In cluster mode, ACME certificates have to be stored in [a KV Store entry](/configuration/acme/#as-a-key-value-store-entry).**
 
 Thanks to the Træfik cluster mode algorithm (based on [the Raft Consensus Algorithm](https://raft.github.io/)), only one instance will contact Let's encrypt to solve the challenges.
 
-The others instances will get ACME certificate from the KV Store entry.
+The others instances will get ACME certificate from the KV Store entry.
diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md
@@ -223,7 +223,7 @@ These variables have to be set on the machine/container that host Træfik.
 
 These variables are described [in this section](/configuration/acme/#provider).
 
-More information about wildcard certificates are available [in this section](/configuration/acme/#wildcard-domain).
+More information about wildcard certificates are available [in this section](/configuration/acme/#wildcard-domains).
 
 ### onHostRule option and provided certificates (with HTTP challenge)
 
diff --git a/docs/user-guide/grpc.md b/docs/user-guide/grpc.md
@@ -45,9 +45,7 @@ We don't need specific configuration to use gRPC in Træfik, we just need to use
 
 This section explains how to use Traefik as reverse proxy for gRPC application with self-signed certificates.
 
-<p align="center">
-<img src="/img/grpc.svg" alt="gRPC architecture" title="gRPC architecture" />
-</p>
+![gRPC architecture](/img/grpc.svg)
 
 ### gRPC Server certificate
 
diff --git a/docs/user-guide/kv-config.md b/docs/user-guide/kv-config.md
@@ -56,7 +56,7 @@ whoami4:
 
 ### Upload the configuration in the Key-value store
 
-We should now fill the store with the Træfik global configuration, as we do with a [TOML file configuration](/toml).  
+We should now fill the store with the Træfik global configuration.  
 To do that, we can send the Key-value pairs via [curl commands](https://www.consul.io/intro/getting-started/kv.html) or via the [Web UI](https://www.consul.io/intro/getting-started/ui.html).
 
 Fortunately, Træfik allows automation of this process using the `storeconfig` subcommand.  
@@ -445,4 +445,4 @@ Then remove the line `storageFile = "acme.json"` from your TOML config file.
 
 That's it!
 
-![](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
+![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
diff --git a/docs/user-guide/marathon.md b/docs/user-guide/marathon.md
@@ -30,7 +30,7 @@ Following is the order by which Traefik tries to identify the port (the first on
 
 ## Applications with multiple ports
 
-Some Marathon applications may expose multiple ports. Traefik supports creating one so-called _service_ per port using [specific labels](/configuration/backends/marathon#service-level).
+Some Marathon applications may expose multiple ports. Traefik supports creating one so-called _segment_ per port using [segment labels](/configuration/backends/marathon#applications-with-multiple-ports-segment-labels).
 
 For instance, assume that a Marathon application exposes a web API on port 80 and an admin interface on port 8080. It would then be possible to make each service available by specifying the following Marathon labels:
 
diff --git a/docs/user-guide/swarm-mode.md b/docs/user-guide/swarm-mode.md
@@ -330,4 +330,4 @@ X-Forwarded-Proto: http
 X-Forwarded-Server: 77fc29c69fe4
 ```
 
-![](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
+![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
diff --git a/docs/user-guide/swarm.md b/docs/user-guide/swarm.md
@@ -178,4 +178,4 @@ X-Forwarded-Proto: http
 X-Forwarded-Server: 8fbc39271b4c
 ```
 
-![](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
+![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)
diff --git a/script/docs-verify-docker-image/Dockerfile b/script/docs-verify-docker-image/Dockerfile
@@ -0,0 +1,20 @@
+FROM alpine:3.7
+
+RUN apk --no-cache --no-progress add \
+    ca-certificates \
+    curl \
+    findutils \
+    ruby-bigdecimal \
+    ruby-ffi \
+    ruby-json \
+    ruby-nokogiri \
+    tini \
+  && gem install --no-document html-proofer
+
+COPY ./validate.sh /validate.sh
+
+WORKDIR /app
+VOLUME ["/tmp","/app"]
+
+ENTRYPOINT ["/sbin/tini","-g","sh"]
+CMD ["/validate.sh"]
diff --git a/script/docs-verify-docker-image/validate.sh b/script/docs-verify-docker-image/validate.sh
@@ -0,0 +1,26 @@
+#!/bin/sh
+
+set -eu
+
+PATH_TO_SITE="/app/site"
+[ -d "${PATH_TO_SITE}" ]
+
+NUMBER_OF_CPUS="$(grep -c processor /proc/cpuinfo)"
+
+
+echo "=== Checking HTML content..."
+
+# Search for all HTML files except the theme's partials
+# and pipe this to htmlproofer with parallel threads
+# (one htmlproofer per vCPU)
+find "${PATH_TO_SITE}" -type f -not -path "/app/site/theme/*" \
+    -name "*.html" -print0 \
+| xargs -0 -r -P "${NUMBER_OF_CPUS}" -I '{}' \
+  htmlproofer \
+  --check-html \
+  --alt_ignore="/traefik.logo.png/" \
+  --url-ignore "/localhost:/,/127.0.0.1:/,/fonts.gstatic.com/,/.minikube/,/github.com\/containous\/traefik\/*edit*/,/github.com\/containous\/traefik\/$/" \
+  '{}'
+## HTML-proofer options at https://github.com/gjtorikian/html-proofer#configuration
+
+echo "= Documentation checked successfuly."
