ci: add docs release versioning (#47)

.github/workflows/docs.yml

@@ -30,5 +30,4 @@ jobs:
         run: make docs-build     
       - name: Deploy Docs
         run: make docs-deploy
-        # - run: mkdocs gh-deploy --force
 

CONTRIBUTING.md

@@ -43,6 +43,14 @@ GitHub provides additional document on [forking a repository](https://help.githu
 ## Finding contributions to work on
 Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
+## Building and Testing Project Documetation
+This project uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to generate versioned documentation automatically. Content for the documentation is auto-generated by referencing the markdown contained in the project's `README.md` files. 
+
+**Local development:**
+- To build the project documentation, run: `make docs-local-docker VERSION=<Semantic Release Version>`. This will build the project using `./docs/Dockerfile` and host the documentation using `mkdocs serve` on port `8000`. 
+
+**Live documentation (GitHub Pages):**
+- A Github workflow is used to build and deploy the documentation to the gh-pages branch: `.github/workflows/docs.yml`
 
 ## Code of Conduct
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).

Makefile

@@ -1,11 +1,66 @@
-docs-build:
-	docker build -t squidfunk/mkdocs-material ./docs/
-
-docs-local-docker:
-	docker build -t squidfunk/mkdocs-material ./docs/
-	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material serve -a 0.0.0.0:8000
-
-docs-deploy:
-	pip install -r ./docs/requirements.txt
-	mike set-default $(git rev-parse --short HEAD)
-	mike deploy --push --update-aliases
+.PHONY: help docs-build docs-local-docker docs-deploy
+
+.DEFAULT_GOAL := help
+
+###########################################################
+#                    ENVIRONMENT VARIABLES
+# Define the environment variables
+###########################################################
+ifeq ($(GITHUB_ACTIONS),true)
+	GIT_USER_NAME := github-actions[bot]
+	GIT_USER_EMAIL := "41898282+github-actions[bot]@users.noreply.github.com"
+else
+	GIT_USER_NAME := $(shell git config user.name)
+	GIT_USER_EMAIL := $(shell git config user.email)
+endif
+
+###########################################################
+#                    COLOR CONFIGURATION
+# Check if the terminal supports color, define color codes
+###########################################################
+COLOR_SUPPORT := $(shell tput colors 2>/dev/null)
+# Define color codes if the terminal supports color
+ifdef COLOR_SUPPORT
+  ifneq ($(shell tput colors),-1)
+    RED := $(shell tput setaf 1)
+    GREEN := $(shell tput setaf 2)
+		CYAN := $(shell tput setaf 6)
+    RESET := $(shell tput sgr0)
+  endif
+endif
+
+###########################################################
+#                    docs-build
+# Build the docs using docker
+###########################################################
+docs-build: ## Build the docs using docker
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "Docs version is: ${GREEN}$(VERSION)${RESET}"
+	docker build -f ./docs/Dockerfile -t docs:$(VERSION) . --build-arg GIT_USER_NAME="$(GIT_USER_NAME)" --build-arg GIT_USER_EMAIL="$(GIT_USER_EMAIL)" --build-arg GITHUB_ACTIONS=$(GITHUB_ACTIONS) --no-cache
+
+###########################################################
+#                    docs-deploy
+# Deploy the docs using 'mike'
+###########################################################
+docs-deploy: ## Deploy the docs using 'mike'
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "Docs version is: ${GREEN}$(VERSION)${RESET}"
+	docker run -t docs:$(VERSION) mike deploy --push --update-aliases $(VERSION) latest
+
+###########################################################
+#                    docs-local-docker
+# Build and run the docs locally using docker and 'serve'
+###########################################################
+docs-local-docker: ## Build and run the docs locally using docker and 'serve'
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "Docs version is: ${GREEN}$(VERSION)${RESET}"
+	docker build -f ./docs/Dockerfile -t docs:$(VERSION) . --build-arg GIT_USER_NAME="$(GIT_USER_NAME)" --build-arg GIT_USER_EMAIL="$(GIT_USER_EMAIL)" --build-arg GITHUB_ACTIONS=$(GITHUB_ACTIONS) --no-cache
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs docs:$(VERSION) mkdocs serve --dev-addr=0.0.0.0:8000
+
+###########################################################
+#                    help
+# Display this help
+###########################################################
+help: ## Display this help
+	@echo -e "Usage: make [TARGET] VERSION=<version>\n"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "${CYAN}%-30s${RESET} %s\n", $$1, $$2}'

docs/Dockerfile

@@ -1,5 +1,9 @@
-FROM squidfunk/mkdocs-material
-COPY ./requirements.txt requirements.txt
-# Set PIP_USER to "no" to suppress warnings. Fine to run as root for local mkdocs development server.
-ENV PIP_USER=no
-RUN pip install -r requirements.txt
+FROM python:3.12
+WORKDIR /build
+COPY . . 
+ARG GIT_USER_NAME GIT_USER_EMAIL GITHUB_ACTIONS
+ENV GIT_USER_NAME=$GIT_USER_NAME GIT_USER_EMAIL=$GIT_USER_EMAIL GITHUB_ACTIONS=$GITHUB_ACTIONS
+
+RUN git config --global user.name "$GIT_USER_NAME" && git config --global user.email "$GIT_USER_EMAIL"
+#RUN git config --global --add safe.directory /build
+RUN pip install -r ./docs/requirements.txt --no-cache-dir

mkdocs.yml

@@ -81,5 +81,6 @@ extra:
   version:
     provider: mike
     default: latest
+    alias: true
 
 copyright: Copyright © 2024 Amazon Web Services