Improve documentation Makefile

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

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 \

docs/scripts/lint.sh

@@ -12,7 +12,7 @@ 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)

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)"