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 -

+![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."