diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a52a7548..9860dc4b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,6 +147,25 @@ ok _/home/user/go/src/github/containous/traefik 0.004s The [documentation site](http://docs.traefik.io/) is built with [mkdocs](http://mkdocs.org/) +### Method 1: `Docker` and `make` + +You can test documentation 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 +``` + +And go to [http://127.0.0.1:8000](http://127.0.0.1:8000). + +### Method 2: `mkdocs` + First make sure you have python and pip installed ```shell diff --git a/Makefile b/Makefile index 2dc206ce7..c5480376a 100644 --- a/Makefile +++ b/Makefile @@ -21,11 +21,15 @@ TRAEFIK_DEV_IMAGE := traefik-dev$(if $(GIT_BRANCH),:$(subst /,-,$(GIT_BRANCH))) 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)", -v "/var/run/docker.sock:/var/run/docker.sock") +TRAEFIK_DOC_IMAGE := traefik-docs DOCKER_BUILD_ARGS := $(if $(DOCKER_VERSION), "--build-arg=DOCKER_VERSION=$(DOCKER_VERSION)",) DOCKER_RUN_OPTS := $(TRAEFIK_ENVS) $(TRAEFIK_MOUNT) "$(TRAEFIK_DEV_IMAGE)" DOCKER_RUN_TRAEFIK := docker run $(INTEGRATION_OPTS) -it $(DOCKER_RUN_OPTS) DOCKER_RUN_TRAEFIK_NOTTY := docker run $(INTEGRATION_OPTS) -i $(DOCKER_RUN_OPTS) +DOCKER_RUN_DOC_PORT := 8000 +DOCKER_RUN_DOC_MOUNT := -v $(CURDIR):/mkdocs +DOCKER_RUN_DOC_OPTS := --rm $(DOCKER_RUN_DOC_MOUNT) -p $(DOCKER_RUN_DOC_PORT):8000 print-%: ; @echo $*=$($*) @@ -89,6 +93,12 @@ 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: docs-image + docker run $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOC_IMAGE) mkdocs serve + +docs-image: + docker build -t $(TRAEFIK_DOC_IMAGE) -f docs.Dockerfile . + clear-static: rm -rf static diff --git a/docs.Dockerfile b/docs.Dockerfile new file mode 100644 index 000000000..cf0d30835 --- /dev/null +++ b/docs.Dockerfile @@ -0,0 +1,11 @@ +FROM alpine + +ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.local/bin + +COPY requirements.txt /mkdocs/ +WORKDIR /mkdocs + +RUN apk --update upgrade \ +&& apk --no-cache --no-progress add py-pip \ +&& rm -rf /var/cache/apk/* \ +&& pip install --user -r requirements.txt diff --git a/mkdocs.yml b/mkdocs.yml index cd2a14d8c..a7fe166b5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: Træfik site_description: Træfik Documentation site_author: containo.us site_url: https://docs.traefik.io +dev_addr: 0.0.0.0:8000 repo_name: 'GitHub' repo_url: 'https://github.com/containous/traefik'