Documentation

Features Are Better When You Know How to Use Them

You’ve found something unclear in the documentation and want to give a try at explaining it better? Let’s see how.

Building Documentation

General

This documentation is built with mkdocs.

Method 1: Docker and make

You can build the documentation and test it locally (with live reloading), using the docs-serve target:

  1. $ make docs-serve
  2. docker build -t traefik-docs -f docs.Dockerfile .
  3. # […]
  4. docker run --rm -v /home/user/go/github/traefik/traefik:/mkdocs -p 8000:8000 traefik-docs mkdocs serve
  5. # […]
  6. [I 170828 20:47:48 server:283] Serving on http://0.0.0.0:8000
  7. [I 170828 20:47:48 handlers:60] Start watching changes
  8. [I 170828 20:47:48 handlers:62] Start detecting changes

Default URL

Your local documentation server will run by default on http://127.0.0.1:8000.

If you only want to build the documentation without serving it locally, you can use the following command:

  1. $ make docs-build
  2. ...

Method 2: mkdocs

First, make sure you have python and pip installed.

  1. $ python --version
  2. Python 2.7.2
  3. $ pip --version
  4. pip 1.5.2

Then, install mkdocs with pip.

  1. pip install --user -r requirements.txt

To build the documentation locally and serve it locally, run mkdocs serve from the root directory. This will start a local server.

  1. $ mkdocs serve
  2. INFO - Building documentation...
  3. INFO - Cleaning site directory
  4. [I 160505 22:31:24 server:281] Serving on http://127.0.0.1:8000
  5. [I 160505 22:31:24 handlers:59] Start watching changes
  6. [I 160505 22:31:24 handlers:61] Start detecting changes

Check the Documentation

To check that the documentation meets standard expectations (no dead links, html markup validity, …), use the docs-verify target.

  1. $ make docs-verify
  2. docker build -t traefik-docs-verify ./script/docs-verify-docker-image ## Build Validator image
  3. ...
  4. docker run --rm -v /home/travis/build/traefik/traefik:/app traefik-docs-verify ## Check for dead links and w3c compliance
  5. === Checking HTML content...
  6. Running ["HtmlCheck", "ImageCheck", "ScriptCheck", "LinkCheck"] on /app/site/basics/index.html on *.html...

Clean & Verify

If you’ve made changes to the documentation, it’s safter to clean it before verifying it.

  1. $ make docs
  2. ...

Will perform all necessary steps for you.

Disabling Documentation Verification

Verification can be disabled by setting the environment variable DOCS_VERIFY_SKIP to true:

  1. DOCS_VERIFY_SKIP=true make docs-verify
  2. ...
  3. DOCS_LINT_SKIP is true: no linting done.