Documentation: Introduces a check stage to validate HTML and links

This commit is contained in:
Damien Duportal 2018-07-12 18:26:03 +02:00 committed by Traefiker Bot
parent 2721c2017c
commit 3ef6bf2118
16 changed files with 116 additions and 30 deletions

View file

@ -16,6 +16,7 @@ env:
script: script:
- echo "Skipping tests... (Tests are executed on SemaphoreCI)" - echo "Skipping tests... (Tests are executed on SemaphoreCI)"
- if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then make docs-verify; fi
before_deploy: before_deploy:
- > - >

View file

@ -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/) 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 ```bash
$ make docs $ 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). 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 First make sure you have python and pip installed
```shell ```bash
$ python --version $ python --version
Python 2.7.2 Python 2.7.2
$ pip --version $ pip --version
@ -190,22 +199,42 @@ pip 1.5.2
Then install mkdocs with pip Then install mkdocs with pip
```shell ```bash
pip install --user -r requirements.txt 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 $ mkdocs serve
INFO - Building documentation... 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 INFO - Cleaning site directory
[I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000 [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:59] Start watching changes
[I 160505 22:31:24 handlers:61] Start detecting 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 ## How to Write a Good Issue

View file

@ -1,4 +1,4 @@
.PHONY: all .PHONY: all docs-verify docs docs-clean docs-build
TRAEFIK_ENVS := \ TRAEFIK_ENVS := \
-e OS_ARCH_ARG \ -e OS_ARCH_ARG \
@ -22,6 +22,7 @@ REPONAME := $(shell echo $(REPO) | tr '[:upper:]' '[:lower:]')
TRAEFIK_IMAGE := $(if $(REPONAME),$(REPONAME),"containous/traefik") 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") 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_IMAGE := traefik-docs
TRAEFIK_DOC_VERIFY_IMAGE := $(TRAEFIK_DOC_IMAGE)-verify
DOCKER_BUILD_ARGS := $(if $(DOCKER_VERSION), "--build-arg=DOCKER_VERSION=$(DOCKER_VERSION)",) DOCKER_BUILD_ARGS := $(if $(DOCKER_VERSION), "--build-arg=DOCKER_VERSION=$(DOCKER_VERSION)",)
DOCKER_RUN_OPTS := $(TRAEFIK_ENVS) $(TRAEFIK_MOUNT) "$(TRAEFIK_DEV_IMAGE)" 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 image: clear-static binary ## clean up static directory and build a docker traefik image
docker build -t $(TRAEFIK_IMAGE) . docker build -t $(TRAEFIK_IMAGE) .
docs-image:
docker build -t $(TRAEFIK_DOC_IMAGE) -f docs.Dockerfile .
docs: docs-image docs: docs-image
docker run $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOC_IMAGE) mkdocs serve docker run $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOC_IMAGE) mkdocs serve
docs-image: docs-build: site
docker build -t $(TRAEFIK_DOC_IMAGE) -f docs.Dockerfile .
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: clear-static:
rm -rf static rm -rf static

View file

@ -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 ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.local/bin
COPY requirements.txt /mkdocs/ COPY requirements.txt /mkdocs/
WORKDIR /mkdocs WORKDIR /mkdocs
VOLUME /mkdocs
RUN apk --update upgrade \ RUN apk --no-cache --no-progress add py-pip \
&& apk --no-cache --no-progress add py-pip \ && pip install --user -r requirements.txt
&& rm -rf /var/cache/apk/* \
&& pip install --user -r requirements.txt

View file

@ -371,7 +371,7 @@ For example, the rule `Host:test1.traefik.io,test2.traefik.io` will request a ce
!!! warning !!! warning
`onHostRule` option can not be used to generate wildcard certificates. `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` ### `storage`

View file

@ -30,7 +30,7 @@
debug = true 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 ## Web UI

View file

@ -3,7 +3,7 @@
</p> </p>
[![Build Status SemaphoreCI](https://semaphoreci.com/api/v1/containous/traefik/branches/master/shields_badge.svg)](https://semaphoreci.com/containous/traefik) [![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) [![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) [![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) [![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)

View file

@ -26,8 +26,8 @@ If this instance fails, another manager will be automatically elected.
## Træfik cluster and Let's Encrypt ## 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. 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.

View file

@ -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). 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) ### onHostRule option and provided certificates (with HTTP challenge)

View file

@ -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. This section explains how to use Traefik as reverse proxy for gRPC application with self-signed certificates.
<p align="center"> ![gRPC architecture](/img/grpc.svg)
<img src="/img/grpc.svg" alt="gRPC architecture" title="gRPC architecture" />
</p>
### gRPC Server certificate ### gRPC Server certificate

View file

@ -56,7 +56,7 @@ whoami4:
### Upload the configuration in the Key-value store ### 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). 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. 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! That's it!
![](https://i.giphy.com/ujUdrdpX7Ok5W.gif) ![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)

View file

@ -30,7 +30,7 @@ Following is the order by which Traefik tries to identify the port (the first on
## Applications with multiple ports ## 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: 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:

View file

@ -330,4 +330,4 @@ X-Forwarded-Proto: http
X-Forwarded-Server: 77fc29c69fe4 X-Forwarded-Server: 77fc29c69fe4
``` ```
![](https://i.giphy.com/ujUdrdpX7Ok5W.gif) ![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)

View file

@ -178,4 +178,4 @@ X-Forwarded-Proto: http
X-Forwarded-Server: 8fbc39271b4c X-Forwarded-Server: 8fbc39271b4c
``` ```
![](https://i.giphy.com/ujUdrdpX7Ok5W.gif) ![GIF Magica](https://i.giphy.com/ujUdrdpX7Ok5W.gif)

View file

@ -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"]

View file

@ -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."