Improve documentation Makefile
This commit is contained in:
Tom Moulard
GitHub
parent
7c4bf602f0
commit
ad3625bef3
5 changed files with 47 additions and 36 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
For more information show `webui/readme.md`
|
||||
For more information show `webui/readme.md`
|
||||
|
|
|
|||
Loading…
Reference in a new issue