From 3ef6bf2118cd1544a7a58435b7d75b02c7157621 Mon Sep 17 00:00:00 2001
From: Damien Duportal
Date: Thu, 12 Jul 2018 18:26:03 +0200
Subject: [PATCH] Documentation: Introduces a check stage to validate HTML and
links
---
.travis.yml | 1 +
CONTRIBUTING.md | 45 +++++++++++++++++----
Makefile | 19 +++++++--
docs.Dockerfile | 9 ++---
docs/configuration/acme.md | 2 +-
docs/configuration/api.md | 2 +-
docs/index.md | 2 +-
docs/user-guide/cluster.md | 4 +-
docs/user-guide/examples.md | 2 +-
docs/user-guide/grpc.md | 4 +-
docs/user-guide/kv-config.md | 4 +-
docs/user-guide/marathon.md | 2 +-
docs/user-guide/swarm-mode.md | 2 +-
docs/user-guide/swarm.md | 2 +-
script/docs-verify-docker-image/Dockerfile | 20 +++++++++
script/docs-verify-docker-image/validate.sh | 26 ++++++++++++
16 files changed, 116 insertions(+), 30 deletions(-)
create mode 100644 script/docs-verify-docker-image/Dockerfile
create mode 100644 script/docs-verify-docker-image/validate.sh
diff --git a/.travis.yml b/.travis.yml
index d119e792c..2680b1e9e 100644
--- 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
index 688b88e0c..1f6a4ac5e 100644
--- 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
index bba47bc7e..02200df1e 100644
--- 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
index cf0d30835..946c26391 100644
--- 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
index fd4501bae..0ffee45cc 100644
--- 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
index b2db8517a..a5d6f5f25 100644
--- 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
index 52f85d639..e466c3f6d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,7 +3,7 @@
[![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
index 111527641..8c03d2798 100644
--- 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.
\ No newline at end of file
+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
index 70a6f5895..51bc7c1be 100644
--- 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
index a4bda1bc7..55ba25bc9 100644
--- 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.
-
-
-
+![gRPC architecture](/img/grpc.svg)
### gRPC Server certificate
diff --git a/docs/user-guide/kv-config.md b/docs/user-guide/kv-config.md
index 3b8ad9661..7fe28ee73 100644
--- 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
index 961687575..d437ff1d5 100644
--- 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
index 3d713127c..0ffbbf799 100644
--- 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
index 638a11300..fa018476e 100644
--- 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
new file mode 100644
index 000000000..5e4dba6a8
--- /dev/null
+++ 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
new file mode 100644
index 000000000..17563a0d3
--- /dev/null
+++ 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."