Documentation Revamp

Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>

docs/content/contributing/advocating.md

@@ -0,0 +1,10 @@
+# Advocating
+
+Spread the Love & Tell Us about It
+{: .subtitle }
+
+There are many ways to contribute to the project, and there is one that always spark joy: when we see/read about users talking about how Traefik helps them solve their problems.
+
+If you're talking about Traefik, [let us know](https://blog.containo.us/spread-the-love-ba5a40aa72e7) and we'll promote your enthusiasm!
+
+Also, if you've written about Traefik or shared useful information you'd like to promote, feel free to add links in the [dedicated wiki page on Github](https://github.com/containous/traefik/wiki/Awesome-Traefik).

docs/content/contributing/building-testing.md

@@ -0,0 +1,181 @@
+# Building and Testing
+
+Compile and Test Your Own Traefik!
+{: .subtitle }
+
+So you want to build your own Traefik binary from the sources?
+Let's see how.
+
+## Building
+
+You need either [Docker](https://github.com/docker/docker) and `make` (Method 1), or `go` (Method 2) in order to build Traefik.
+For changes to its dependencies, the `dep` dependency management tool is required.
+
+### Method 1: Using `Docker` and `Makefile`
+
+Run make with the `binary` target.
+This will create binaries for the Linux platform in the `dist` folder.
+
+```bash
+$ make binary
+docker build -t traefik-webui -f webui/Dockerfile webui
+Sending build context to Docker daemon  2.686MB
+Step 1/11 : FROM node:8.15.0
+ ---> 1f6c34f7921c
+[...]
+Successfully built ce4ff439c06a
+Successfully tagged traefik-webui:latest
+[...]
+docker build  -t "traefik-dev:4475--feature-documentation" -f build.Dockerfile .
+Sending build context to Docker daemon    279MB
+Step 1/10 : FROM golang:1.11-alpine
+ ---> f4bfb3d22bda
+[...]
+Successfully built 5c3c1a911277
+Successfully tagged traefik-dev:4475--feature-documentation
+docker run  -e "TEST_CONTAINER=1" -v "/var/run/docker.sock:/var/run/docker.sock" -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -e VERBOSE -e VERSION -e CODENAME -e TESTDIRS -e CI -e CONTAINER=DOCKER		 -v "/home/ldez/sources/go/src/github.com/containous/traefik/"dist":/go/src/github.com/containous/traefik/"dist"" "traefik-dev:4475--feature-documentation" ./script/make.sh generate binary
+---> Making bundle: generate (in .)
+removed 'autogen/gentemplates/gen.go'
+removed 'autogen/genstatic/gen.go'
+
+---> Making bundle: binary (in .)
+
+$ ls dist/
+traefik*
+```
+
+### Method 2: Using `go`
+
+You need `go` v1.9+.
+
+!!! tip "Source Directory"
+ 
+    It is recommended that you clone Traefik into the `~/go/src/github.com/containous/traefik` directory.
+    This is the official golang workspace hierarchy that will allow dependencies to be properly resolved.
+
+!!! note "Environment"
+
+    Set your `GOPATH` and `PATH` variable to be set to `~/go` via:
+    
+    ```bash
+    export GOPATH=~/go
+    export PATH=$PATH:$GOPATH/bin
+    ```
+ 
+    For convenience, add `GOPATH` and `PATH` to your `.bashrc` or `.bash_profile`
+    
+    Verify your environment is setup properly by running `$ go env`.
+    Depending on your OS and environment, you should see an output similar to:
+    
+    ```bash
+    GOARCH="amd64"
+    GOBIN=""
+    GOEXE=""
+    GOHOSTARCH="amd64"
+    GOHOSTOS="linux"
+    GOOS="linux"
+    GOPATH="/home/<yourusername>/go"
+    GORACE=""
+    ## ... and the list goes on
+    ```
+
+#### Build Traefik
+
+Once you've set up your go environment and cloned the source repository, you can build Traefik.
+Beforehand, you need to get `go-bindata` (the first time) in order to be able to use the `go generate` command (which is part of the build process).
+
+```bash
+cd ~/go/src/github.com/containous/traefik
+
+# Get go-bindata. (Important: the ellipses are required.)
+go get github.com/containous/go-bindata/...
+
+# Let's build
+
+# generate
+# (required to merge non-code components into the final binary, such as the web dashboard and the provider's templates)
+go generate
+
+# Standard go build
+go build ./cmd/traefik
+```
+
+You will find the Traefik executable (`traefik`) in the `~/go/src/github.com/containous/traefik` directory.
+
+### Updating the templates
+
+If you happen to update the provider's templates (located in `/templates`), you must run `go generate` to update the `autogen` package.
+
+### Setting up dependency management
+
+The [dep](https://github.com/golang/dep) command is not required for building;
+however, it is necessary if you need to update the dependencies (i.e., add, update, or remove third-party packages).
+
+You need [dep](https://github.com/golang/dep) >= 0.5.0.
+
+If you want to add a dependency, use `dep ensure -add` to have [dep](https://github.com/golang/dep) put it into the vendor folder and update the dep manifest/lock files (`Gopkg.toml` and `Gopkg.lock`, respectively).
+
+A following `make dep-prune` run should be triggered to trim down the size of the vendor folder.
+The final result must be committed into VCS.
+
+Here's a full example using dep to add a new dependency:
+
+```bash
+# install the new main dependency github.com/foo/bar and minimize vendor size
+$ dep ensure -add github.com/foo/bar
+# generate (Only required to integrate other components such as web dashboard)
+$ go generate
+# Standard go build
+$ go build ./cmd/traefik
+```
+
+## Testing
+
+### Method 1: `Docker` and `make`
+
+Run unit tests using the `test-unit` target.
+Run integration tests using the `test-integration` target.
+Run all tests (unit and integration) using the `test` target.
+
+```bash
+$ make test-unit
+docker build -t "traefik-dev:your-feature-branch" -f build.Dockerfile .
+# […]
+docker run --rm -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/user/go/src/github/containous/traefik/dist:/go/src/github.com/containous/traefik/dist" "traefik-dev:your-feature-branch" ./script/make.sh generate test-unit
+---> Making bundle: generate (in .)
+removed 'gen.go'
+
+---> Making bundle: test-unit (in .)
++ go test -cover -coverprofile=cover.out .
+ok      github.com/containous/traefik   0.005s  coverage: 4.1% of statements
+
+Test success
+```
+
+For development purposes, you can specify which tests to run by using (only works the `test-integration` target):
+
+```bash
+# Run every tests in the MyTest suite
+TESTFLAGS="-check.f MyTestSuite" make test-integration
+
+# Run the test "MyTest" in the MyTest suite
+TESTFLAGS="-check.f MyTestSuite.MyTest" make test-integration
+
+# Run every tests starting with "My", in the MyTest suite
+TESTFLAGS="-check.f MyTestSuite.My" make test-integration
+
+# Run every tests ending with "Test", in the MyTest suite
+TESTFLAGS="-check.f MyTestSuite.*Test" make test-integration
+```
+
+More: https://labix.org/gocheck
+
+### Method 2: `go`
+
+Unit tests can be run from the cloned directory using `$ go test ./...` which should return `ok`, similar to:
+
+```test
+ok      _/home/user/go/src/github/containous/traefik    0.004s
+```
+
+Integration tests must be run from the `integration/` directory and require the `-integration` switch: `$ cd integration && go test -integration ./...`.

docs/content/contributing/data-collection.md

@@ -0,0 +1,112 @@
+# Data Collection
+
+Understanding How Traefik is Being Used
+{: .subtitle }
+
+## Configuration Example
+
+**By default, this feature is disabled;** but to allow us understand better how you use Traefik, please enable the data collection option.
+
+??? example "Enabling Data Collection with TOML"
+
+    ```toml
+    [Global]
+        # Send anonymous usage data
+        # Default: false
+        #
+        sendAnonymousUsage = true
+    ```
+
+??? example "Enabling Data Collection with the CLI"
+
+    ```bash
+    ./traefik --sendAnonymousUsage=true
+    ```
+    
+## Collected Data
+
+This feature comes from the public proposal [here](https://github.com/containous/traefik/issues/2369).
+
+In order to help us learn more about how Traefik is being used and improve it, we collect anonymous usage statistics from running instances.
+Those data help us prioritize our developments and focus on what's important for our users (for example, which provider is popular, and which is not).
+
+### What's collected / when ?
+
+Once a day (the first call begins 10 minutes after the start of Traefik), we collect:
+
+- the Traefik version number
+- a hash of the configuration
+- an **anonymized version** of the static configuration (token, user name, password, URL, IP, domain, email, etc, are removed).
+
+!!! note
+    We do not collect the dynamic configuration information (routers & services).
+    We do not collect these data to run advertising programs.
+    We do not sell these data to third-parties.
+
+### Example of Collected Data
+
+??? example "Original configuration"
+
+    ```toml
+    [entryPoints]
+        [entryPoints.http]
+           address = ":80"
+    
+    [api]
+    
+    [Docker]
+      endpoint = "tcp://10.10.10.10:2375"
+      domain = "foo.bir"
+      exposedByDefault = true
+      swarmMode = true
+    
+      [Docker.TLS]
+        ca = "dockerCA"
+        cert = "dockerCert"
+        key = "dockerKey"
+        insecureSkipVerify = true
+    
+    [ECS]
+      domain = "foo.bar"
+      exposedByDefault = true
+      clusters = ["foo-bar"]
+      region = "us-west-2"
+      accessKeyID = "AccessKeyID"
+      secretAccessKey = "SecretAccessKey"
+    ```
+
+??? example "Resulting Obfuscated Configuration"
+
+    ```toml
+    [entryPoints]
+        [entryPoints.http]
+           address = ":80"
+    
+    [api]
+    
+    [Docker]
+      endpoint = "xxxx"
+      domain = "xxxx"
+      exposedByDefault = true
+      swarmMode = true
+    
+      [Docker.TLS]
+        ca = "xxxx"
+        cert = "xxxx"
+        key = "xxxx"
+        insecureSkipVerify = false
+    
+    [ECS]
+      domain = "xxxx"
+      exposedByDefault = true
+      clusters = []
+      region = "us-west-2"
+      accessKeyID = "xxxx"
+      secretAccessKey = "xxxx"
+    ```
+
+## The Code for Data Collection
+
+If you want to dig into more details, here is the source code of the collecting system: [collector.go](https://github.com/containous/traefik/blob/master/collector/collector.go)
+
+By default we anonymize all configuration fields, except fields tagged with `export=true`.

docs/content/contributing/documentation.md

@@ -0,0 +1,100 @@
+# Documentation
+
+Features Are Better When You Know How to Use Them
+{: .subtitle }
+
+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](http://docs.traefik.io/) is built with [mkdocs](http://mkdocs.org/).
+
+### Method 1: `Docker` and `make`
+
+You can build the documentation and test it locally (with live reloading), using the `docs` target:
+
+```bash
+$ make docs
+docker build -t traefik-docs -f docs.Dockerfile .
+# […]
+docker run  --rm -v /home/user/go/github/containous/traefik:/mkdocs -p 8000:8000 traefik-docs mkdocs serve
+# […]
+[I 170828 20:47:48 server:283] Serving on http://0.0.0.0:8000
+[I 170828 20:47:48 handlers:60] Start watching changes
+[I 170828 20:47:48 handlers:62] Start detecting changes
+```
+
+!!! tip "Default URL"
+
+    Your local documentation server will run by default on [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
+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.
+
+```bash
+$ python --version
+Python 2.7.2
+$ pip --version
+pip 1.5.2
+```
+
+Then, install mkdocs with `pip`.
+
+```bash
+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.
+
+```bash
+$ mkdocs serve
+INFO    -  Building documentation...
+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
+```
+
+### Check the Documentation
+
+To check that the documentation meets standard expectations (no dead links, html markup validity, ...), use the `docs-verify` target.
+
+```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...
+```
+
+!!! note "Clean & Verify"
+
+    If you've made changes to the documentation, it's safter to clean it before verifying it. 
+
+    ```bash
+    $ make docs-clean docs-verify
+    ...
+    ```
+
+!!! note "Disabling Documentation Verification"
+
+    Verification can be disabled by setting the environment variable `DOCS_VERIFY_SKIP` to `true`:
+    
+    ```shell
+    DOCS_VERIFY_SKIP=true make docs-verify
+    ...
+    DOCS_LINT_SKIP is true: no linting done.
+    ```

docs/content/contributing/submitting-issues.md

@@ -0,0 +1,45 @@
+# Submitting Issues
+
+Help Us Help You!
+{: .subtitle }
+
+We use the [GitHub issue tracker](https://github.com/containous/traefik/issues) to keep track of issues in Traefik. 
+
+The process of sorting and checking the issues is a daunting task, and requires a lot of work (more than an hour a day ... just for sorting).
+To save us some time and get quicker feedback, be sure to follow the guide lines below.
+
+!!! important "Getting Help Vs Reporting an Issue"
+
+    The issue tracker is not a general support forum, but a place to report bugs and asks for new features.
+    
+    For end-user related support questions, try using first:
+    
+    - the Traefik community Slack channel: [![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)
+    - [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag)
+
+## Issue Title
+
+The title must be short and descriptive. (~60 characters)
+
+## Description
+
+Follow the [issue template](https://github.com/containous/traefik/blob/master/.github/ISSUE_TEMPLATE.md) as much as possible, and make use of the `traefik bug` command if you can (see the [video on Youtube](https://www.youtube.com/watch?v=Lyz62L8m93I)).
+
+Explain us in which conditions you encountered the issue, what is your context.
+
+Remain as clear and concise as possible
+
+Take time to polish the format of your message so we'll enjoy reading it and working on it. 
+Help the readers focus on what matters, and help them understand the structure of your message (see the [Github Markdown Syntax](https://help.github.com/articles/github-flavored-markdown)).
+
+## Feature Request
+
+Traefik is an open-source project and aims to be the best edge router possible.
+
+Remember when asking for new features that these must be useful to the majority (and not only useful in edge case scenarios, or hack-like setups).
+
+Do you best to explain what you're looking for, and why it would improve Traefik for everyone. 
+
+## International English
+
+Every maintainer / Traefik user is not a native English speaker, so if you feel sometimes that some messages sound rude, remember that it probably is a language barrier problem from someone willing to help you.

docs/content/contributing/submitting-pull-requests.md

@@ -0,0 +1,45 @@
+# Submitting Pull Requests
+
+A Quick Guide for Efficient Contributions
+{: .subtitle }
+
+So you've decide to improve Traefik? 
+Thank You! 
+Now the last step is to submit your Pull Request in a way that makes sure it gets the attention it deserves.
+
+Let's go though the classic pitfalls to make sure everything is right. 
+
+## Title
+
+The title must be short and descriptive. (~60 characters)
+
+## Description
+
+Follow the [pull request template](https://github.com/containous/traefik/blob/master/.github/PULL_REQUEST_TEMPLATE.md) as much as possible.
+
+Explain the conditions which led you to write this PR: give us context.
+The context should lead to something, an idea or a problem that you’re facing.
+
+Remain clear and concise.
+
+Take time to polish the format of your message so we'll enjoy reading it and working on it.
+Help the readers focus on what matters, and help them understand the structure of your message (see the [Github Markdown Syntax](https://help.github.com/articles/github-flavored-markdown)).
+
+## PR Content
+
+- Make it small.
+- One feature per Pull Request.
+- Write useful descriptions and titles.
+- Avoid re-formatting code that is not on the path of your PR.
+- Make sure the [code builds](building-testing.md).
+- Make sure [all tests pass](building-testing.md).
+- Add tests.
+- Address review comments in terms of additional commits (and don't amend/squash existing ones unless the PR is trivial).
+
+!!! note "third-party dependencies"
+
+    If a PR involves changes to third-party dependencies, the commits pertaining to the vendor folder and the manifest/lock file(s) should be committed separated.
+
+!!! tip "10 Tips for Better Pull Requests"
+
+    We enjoyed this article, maybe you will too! [10 tips for better pull requests](http://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/).

docs/content/contributing/thank-you.md

@@ -0,0 +1,10 @@
+# Thank You!
+
+_You_ Made It
+{: .subtitle}
+
+Traefik truly is an [open-source project](https://github.com/containous/traefik/),
+and wouldn't have become what it is today without the help of our [many contributors](https://github.com/containous/traefik/graphs/contributors) (at the time of writing this),
+not accounting for people having helped with issues, tests, comments, articles, ... or just enjoying it and letting others know.
+
+So once again, thank you for your invaluable help on making Traefik such a good product.