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