From 195c93bb3143c479b5af555db61c20d62bb429da Mon Sep 17 00:00:00 2001
From: Randy Fay <randy@randyfay.com>
Date: Tue, 26 Mar 2024 07:33:53 -0600
Subject: [PATCH] docs: update dev docs to run mkdocs locally (#6016) [skip ci]

---
 Makefile                                | 10 ++++++++--
 docs/content/developers/testing-docs.md | 15 ++++++++++++++-
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 50bc9992b3e..65d0e3e4975 100644
--- a/Makefile
+++ b/Makefile
@@ -165,12 +165,18 @@ mkdocs:
 # It works best with mkdocs installed, `pip3 install mkdocs`,
 # see https://www.mkdocs.org/user-guide/installation/
 # But it will also work using docker.
+MKDOCS_TAG := 1.5.2
+ifeq ($(BUILD_ARCH),arm64)
+    MKDOCS_TAG := arm64v8-$(MKDOCS_TAG)
+endif
 mkdocs-serve:
+	set -x; \
 	if command -v mkdocs >/dev/null ; then \
   		mkdocs serve; \
 	else \
-		docker run -it --rm -p 8000:8000 -v "${PWD}:/docs" -e "ADD_MODULES=mkdocs-material mkdocs-redirects mkdocs-minify-plugin mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin" -e "LIVE_RELOAD_SUPPORT=true" -e "FAST_MODE=true" -e "DOCS_DIRECTORY=./docs" polinux/mkdocs:1.2.3; \
-	fi
+		docker run -it -p 8000:8000 -v "${PWD}:/docs" -e "ADD_MODULES=mkdocs-material mkdocs-redirects mkdocs-minify-plugin mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin" -e "LIVE_RELOAD_SUPPORT=true" -e "FAST_MODE=true" -e "DOCS_DIRECTORY=./docs" "polinux/mkdocs:$(MKDOCS_TAG)"; \
+	fi; \
+	set +x
 
 # Install markdown-link-check locally with "npm install -g markdown-link-check"
 markdown-link-check:
diff --git a/docs/content/developers/testing-docs.md b/docs/content/developers/testing-docs.md
index 748649593e7..e6cd64141c7 100644
--- a/docs/content/developers/testing-docs.md
+++ b/docs/content/developers/testing-docs.md
@@ -44,7 +44,20 @@ This will launch a web server on port 8000 and automatically refresh pages as th
     It’s easiest to [install MkDocs locally](https://www.mkdocs.org/user-guide/installation/), but you don’t have to. The `make mkdocs-serve` command will look for and use a local binary, otherwise using `make` to build and serve the documentation. If you don’t have `make` installed on your system, you can directly run the command it would have instead:
 
     ```
-    docker run -it -p 8000:8000 -v "${PWD}:/docs" -e "ADD_MODULES=mkdocs-material mkdocs-redirects mkdocs-minify-plugin mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin" -e "LIVE_RELOAD_SUPPORT=true" -e "FAST_MODE=true" -e "DOCS_DIRECTORY=./docs" polinux/mkdocs;
+    TAG=$(arch)
+    if [ "${TAG}" = "arm64" ]; then TAG="${TAG}v8-1.5.2"; else TAG=1.5.2; fi
+    docker run -it -p 8000:8000 -v "${PWD}:/docs" -e "ADD_MODULES=mkdocs-material mkdocs-redirects mkdocs-minify-plugin mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin" -e "LIVE_RELOAD_SUPPORT=true" -e "FAST_MODE=true" -e "DOCS_DIRECTORY=./docs" "polinux/mkdocs:$TAG"
+    ```
+
+!!!tip "Installing mkdocs locally on macOS"
+    On macOS with recent versions of Homebrew use this technique to install mkdocs:
+
+    ```bash
+    brew install pipx
+    export PIPX_BIN_DIR=/usr/local/bin
+    pipx install mkdocs
+    pipx runpip mkdocs install -r docs/mkdocs-pip-requirements
+    pipx ensurepath
     ```
 
 ## Check Markdown for Errors