From ad3625bef305ad9eb200dabe831cb16cc9daf881 Mon Sep 17 00:00:00 2001 From: Tom Moulard Date: Fri, 15 Apr 2022 16:16:08 +0200 Subject: [PATCH] Improve documentation Makefile --- docs/Makefile | 41 +++++++++++-------- docs/check.Dockerfile | 12 +++--- docs/scripts/lint.sh | 8 ++-- docs/scripts/verify.sh | 20 ++++----- .../DONT-EDIT-FILES-IN-THIS-DIRECTORY.md | 2 +- 5 files changed, 47 insertions(+), 36 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 85546ac68..501cbdbad 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,4 +1,3 @@ - ####### # This Makefile contains all targets related to the documentation ####### @@ -16,41 +15,51 @@ DOCKER_RUN_DOC_MOUNTS := -v $(CURDIR):/mkdocs DOCKER_RUN_DOC_OPTS := --rm $(DOCKER_RUN_DOC_MOUNTS) -p $(DOCKER_RUN_DOC_PORT):8000 # Default: generates the documentation into $(SITE_DIR) +.PHONY: docs docs: docs-clean docs-image docs-lint docs-build docs-verify # Writer Mode: build and serve docs on http://localhost:8000 with livereload +.PHONY: docs-serve docs-serve: docs-image docker run $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOCS_BUILD_IMAGE) mkdocs serve ## Pull image for doc building +.PHONY: docs-pull-images docs-pull-images: - grep --no-filename -E '^FROM' ./*.Dockerfile | awk '{print $$2}' | sort | uniq | xargs -P 6 -n 1 docker pull + grep --no-filename -E '^FROM' ./*.Dockerfile \ + | awk '{print $$2}' \ + | sort \ + | uniq \ + | xargs -P 6 -n 1 docker pull # Utilities Targets for each step +.PHONY: docs-image docs-image: docker build -t $(TRAEFIK_DOCS_BUILD_IMAGE) -f docs.Dockerfile ./ +.PHONY: docs-build docs-build: docs-image docker run $(DOCKER_RUN_DOC_OPTS) $(TRAEFIK_DOCS_BUILD_IMAGE) sh -c "mkdocs build \ && chown -R $(shell id -u):$(shell id -g) ./site" +.PHONY: docs-verify docs-verify: docs-build - @if [ "$(DOCS_VERIFY_SKIP)" != "true" ]; then \ - docker build -t $(TRAEFIK_DOCS_CHECK_IMAGE) -f check.Dockerfile ./; \ - docker run --rm -v $(CURDIR):/app $(TRAEFIK_DOCS_CHECK_IMAGE) /verify.sh; \ - else \ - echo "DOCS_VERIFY_SKIP is true: no verification done."; \ - fi +ifneq ("$(DOCS_VERIFY_SKIP)", "true") + docker build -t $(TRAEFIK_DOCS_CHECK_IMAGE) -f check.Dockerfile ./ + docker run --rm -v $(CURDIR):/app $(TRAEFIK_DOCS_CHECK_IMAGE) /verify.sh +else + echo "DOCS_VERIFY_SKIP is true: no verification done." +endif +.PHONY: docs-lint docs-lint: - @if [ "$(DOCS_LINT_SKIP)" != "true" ]; then \ - docker build -t $(TRAEFIK_DOCS_CHECK_IMAGE) -f check.Dockerfile ./ && \ - docker run --rm -v $(CURDIR):/app $(TRAEFIK_DOCS_CHECK_IMAGE) /lint.sh; \ - else \ - echo "DOCS_LINT_SKIP is true: no linting done."; \ - fi +ifneq ("$(DOCS_LINT_SKIP)", "true") + docker build -t $(TRAEFIK_DOCS_CHECK_IMAGE) -f check.Dockerfile ./ + docker run --rm -v $(CURDIR):/app $(TRAEFIK_DOCS_CHECK_IMAGE) /lint.sh +else + echo "DOCS_LINT_SKIP is true: no linting done." +endif +.PHONY: docs-clean docs-clean: rm -rf $(SITE_DIR) - -.PHONY: all docs-verify docs docs-clean docs-build docs-lint diff --git a/docs/check.Dockerfile b/docs/check.Dockerfile index 53b914c66..92321d109 100644 --- a/docs/check.Dockerfile +++ b/docs/check.Dockerfile @@ -1,18 +1,20 @@ - FROM alpine:3.14 as alpine RUN apk --no-cache --no-progress add \ + build-base \ libcurl \ + libxml2-dev \ + libxslt-dev \ ruby \ ruby-bigdecimal \ + ruby-dev \ ruby-etc \ ruby-ffi \ ruby-json \ - ruby-nokogiri \ - ruby-dev \ - build-base + zlib-dev -RUN gem install html-proofer --version 3.19.0 --no-document -- --use-system-libraries +RUN gem install nokogiri --version 1.13.3 --no-document -- --use-system-libraries +RUN gem install html-proofer --version 3.19.3 --no-document -- --use-system-libraries # After Ruby, some NodeJS YAY! RUN apk --no-cache --no-progress add \ diff --git a/docs/scripts/lint.sh b/docs/scripts/lint.sh index 668af9178..a46066df8 100755 --- a/docs/scripts/lint.sh +++ b/docs/scripts/lint.sh @@ -12,15 +12,15 @@ echo "== Linting Markdown" # Uses the file ".markdownlint.json" for setup cd "${BASE_DIR}" || exit 1 -LINTER_EXCLUSIONS="$(find "${BASE_DIR}/content" -type f -name '.markdownlint.json')" \ +LINTER_EXCLUSIONS="$(find "${BASE_DIR}/content" -type f -name '.markdownlint.json')" GLOBAL_LINT_OPTIONS="--config ${BASE_DIR}/.markdownlint.json" # Lint the specific folders (containing linter specific rulesets) for LINTER_EXCLUSION in ${LINTER_EXCLUSIONS} do - markdownlint --config "${LINTER_EXCLUSION}" "$(dirname "${LINTER_EXCLUSION}")" || EXIT_CODE=1 - # Add folder to the ignore list for global lint - GLOBAL_LINT_OPTIONS="${GLOBAL_LINT_OPTIONS} --ignore=$(dirname "${LINTER_EXCLUSION}")" + markdownlint --config "${LINTER_EXCLUSION}" "$(dirname "${LINTER_EXCLUSION}")" || EXIT_CODE=1 + # Add folder to the ignore list for global lint + GLOBAL_LINT_OPTIONS="${GLOBAL_LINT_OPTIONS} --ignore=$(dirname "${LINTER_EXCLUSION}")" done # Lint all the content, excluding the previously done` diff --git a/docs/scripts/verify.sh b/docs/scripts/verify.sh index 99ca0083d..81584223d 100755 --- a/docs/scripts/verify.sh +++ b/docs/scripts/verify.sh @@ -4,7 +4,7 @@ PATH_TO_SITE="${1:-/app/site}" set -eu -[ -d "${PATH_TO_SITE}" ] +[ ! -d "${PATH_TO_SITE}" ] && echo "= Cannot check HTML content: no site asset found" && exit 1 NUMBER_OF_CPUS="$(grep -c processor /proc/cpuinfo)" @@ -14,16 +14,16 @@ echo "=== Checking HTML content..." # 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 \ + -name "*.html" -print0 \ | xargs -0 -r -P "${NUMBER_OF_CPUS}" -I '{}' \ - htmlproofer \ - --check-html \ - --check_external_hash \ - --alt_ignore="/traefikproxy-vertical-logo-color.svg/" \ - --http_status_ignore="0,500,501,503" \ - --file_ignore="/404.html/" \ - --url_ignore="/https://groups.google.com/a/traefik.io/forum/#!forum/security/,/localhost:/,/127.0.0.1:/,/fonts.gstatic.com/,/.minikube/,/github.com\/traefik\/traefik\/*edit*/,/github.com\/traefik\/traefik/,/doc.traefik.io/,/github\.com\/golang\/oauth2\/blob\/36a7019397c4c86cf59eeab3bc0d188bac444277\/.+/,/www.akamai.com/,/pilot.traefik.io\/profile/,/traefik.io/,/doc.traefik.io\/traefik-mesh/,/www.mkdocs.org/,/squidfunk.github.io/,/ietf.org/,/www.namesilo.com/,/www.youtube.com/,/www.linode.com/,/www.alibabacloud.com/,/www.cloudxns.net/,/www.vultr.com/,/vscale.io/,/hetzner.com/,/docs.github.com/" \ - '{}' 1>/dev/null + htmlproofer \ + --check-html \ + --check_external_hash \ + --alt_ignore="/traefikproxy-vertical-logo-color.svg/" \ + --http_status_ignore="0,500,501,503" \ + --file_ignore="/404.html/" \ + --url_ignore="/https://groups.google.com/a/traefik.io/forum/#!forum/security/,/localhost:/,/127.0.0.1:/,/fonts.gstatic.com/,/.minikube/,/github.com\/traefik\/traefik\/*edit*/,/github.com\/traefik\/traefik/,/doc.traefik.io/,/github\.com\/golang\/oauth2\/blob\/36a7019397c4c86cf59eeab3bc0d188bac444277\/.+/,/www.akamai.com/,/pilot.traefik.io\/profile/,/traefik.io/,/doc.traefik.io\/traefik-mesh/,/www.mkdocs.org/,/squidfunk.github.io/,/ietf.org/,/www.namesilo.com/,/www.youtube.com/,/www.linode.com/,/www.alibabacloud.com/,/www.cloudxns.net/,/www.vultr.com/,/vscale.io/,/hetzner.com/,/docs.github.com/" \ + '{}' 1>/dev/null ## HTML-proofer options at https://github.com/gjtorikian/html-proofer#configuration echo "= Documentation checked successfully." diff --git a/webui/static/DONT-EDIT-FILES-IN-THIS-DIRECTORY.md b/webui/static/DONT-EDIT-FILES-IN-THIS-DIRECTORY.md index a0965fd38..03873182c 100644 --- a/webui/static/DONT-EDIT-FILES-IN-THIS-DIRECTORY.md +++ b/webui/static/DONT-EDIT-FILES-IN-THIS-DIRECTORY.md @@ -1 +1 @@ -For more information show `webui/readme.md` \ No newline at end of file +For more information show `webui/readme.md`