docs: modify the workflow for docs release and update documentation (#…

…124)

.github/workflows/docs.yml

@@ -2,7 +2,7 @@
 ## Process
 # 1. When changes are made to documentation files and pushed to the main branch, the workflow in this file is triggered.
 # 2. Copy the repository's contents to the runner, so the workflow can access them.
-# 3. `make docs-deploy` is run inside Docker container to deploy the documentation to GitHub Pages.
+# 3. `make docs-deploy-prod` is run inside Docker container to deploy the documentation to GitHub Pages.
 # Currently using fixed version and alias until release
 #====================================================================================================
 name: Build Docs and Publish to gh-pages
@@ -53,5 +53,5 @@ jobs:
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
       - name: Deploy Docs
-        run: make docs-deploy VERSION="$VERSION" ALIAS="$ALIAS"
+        run: make docs-deploy-prod VERSION="$VERSION" ALIAS="$ALIAS" PUSH_REMOTE="true"
 

Makefile

@@ -19,39 +19,43 @@ ifdef COLOR_SUPPORT
   endif
 endif
 
-.PHONY: docs-build
-docs-build: ## Build the docs using docker. Example: `make docs-build VERSION=v1.0.0`
-	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'make docs-build VERSION=v1.0.0'. 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)" \
+.PHONY: docs-deploy-prod
+docs-deploy-prod: ## Build and deploy the docs using 'mike'. Same as `docs-build` but requires PUSH_REMOTE to be explicitly set to deploy to remote branch. Usage: `make docs-deploy-prod VERSION=v1.0.0 ALIAS=latest PUSH_REMOTE=true`
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'make docs-deploy-prod VERSION=v1.0.0 ALIAS=latest PUSH_REMOTE=true'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@if [ -z "${ALIAS}" ]; then echo -e "${RED}ALIAS is not set. Example: 'make docs-deploy-prod VERSION=v1.0.0 ALIAS=latest PUSH_REMOTE=true'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@if [ -z "${PUSH_REMOTE}" ]; then echo -e "${RED}PUSH_REMOTE is not set This should be "true" if deploying to prod. Example: 'make docs-deploy-prod VERSION=v1.0.0 ALIAS=latest PUSH_REMOTE=true'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "${GREEN}Docs version is: ${VERSION}:${ALIAS}${RESET}";
+	@docker build -f ./docs/Dockerfile -t docs:${VERSION} -t docs:${ALIAS} . \
+		--build-arg GIT_USER_NAME="${GIT_USER_NAME}" \
+		--build-arg GIT_USER_EMAIL="${GIT_USER_EMAIL}" \
+		--build-arg GITHUB_ACTIONS="${GITHUB_ACTIONS}" \
+		--build-arg VERSION="${VERSION}" \
+		--build-arg ALIAS="${ALIAS}" \
+		--build-arg PUSH_REMOTE=${PUSH_REMOTE} \
 		--no-cache
 
-.PHONY: docs-deploy
-docs-deploy: ## Build and deploy the docs using 'mike'. Example: `make docs-deploy VERSION=v1.0.0 ALIAS=latest`
-	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'make docs-deploy VERSION=v1.0.0'. Run 'make help' for usage. ${RESET}"; exit 1; fi
-	@if [ -z "${ALIAS}" ]; then echo -e "${RED}ALIAS is not set. Example: 'make docs-deploy VERSION=v1.0.0 ALIAS=latest'. 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)" \
+.PHONY: docs-build
+docs-build: ## Build the docs locally as a container image, tagged with version and alias (ex: docs:v1.0.0, docs:latest). Usage: `make docs-build VERSION=v1.0.0 ALIAS=latest`
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'docs-build VERSION=v1.0.0 ALIAS=latest'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@if [ -z "${ALIAS}" ]; then echo -e "${RED}ALIAS is not set. Example: 'docs-build VERSION=v1.0.0 ALIAS=latest'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "${GREEN}Docs version is: ${VERSION}:${ALIAS}${RESET}";
+	@docker build -f ./docs/Dockerfile -t docs:${VERSION} -t docs:${ALIAS} . \
+		--build-arg GIT_USER_NAME="${GIT_USER_NAME}" \
+		--build-arg GIT_USER_EMAIL="${GIT_USER_EMAIL}" \
+		--build-arg GITHUB_ACTIONS="${GITHUB_ACTIONS}" \
+		--build-arg VERSION="${VERSION}" \
+		--build-arg ALIAS="${ALIAS}" \
+		--build-arg PUSH_REMOTE="false" \
 		--no-cache
-	docker run -t docs:$(VERSION) mike deploy $(VERSION) ${ALIAS} --update-aliases
-	docker run -t docs:$(VERSION) mike set-default $(ALIAS) --push --allow-empty
 
-.PHONY: docs-local-docker
-docs-local-docker: ## Build and run the docs locally using docker and 'serve'. Example: `make docs-local-docker VERSION=v1.0.0`
-	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'make docs-local-docker VERSION=v1.0.0'. 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
+.PHONY: docs-run
+docs-run: ## Run a built docs container image locally. Usage: `make docs-run VERSION=v1.0.0 ALIAS=latest`
+	@if [ -z "${VERSION}" ]; then echo -e "${RED}VERSION is not set. Example: 'make docs-run VERSION=v1.0.0 ALIAS=latest'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@if [ -z "${ALIAS}" ]; then echo -e "${RED}ALIAS is not set. Example: 'make docs-run VERSION=v1.0.0 ALIAS=latest'. Run 'make help' for usage. ${RESET}"; exit 1; fi
+	@echo -e "${GREEN}Docs version is: ${VERSION}:${ALIAS}${RESET}";
+	@CONTAINERS=$(shell docker ps -q -f publish=8000) && if [ -n "$$CONTAINERS" ]; then echo -e "${GREEN}Clearing port 8000 and running docs locally. Waiting...${RESET}"; docker stop $$CONTAINERS; fi
+	@docker run -d -p 8000:8000 docs:${VERSION} mike serve --dev-addr=0.0.0.0:8000
+	@echo -e "${GREEN}Docs running at: http://localhost:8000${RESET}"
 
 .PHONY: help
 help: ## Display this help

docs/Dockerfile

@@ -1,9 +1,12 @@
 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
-
+ARG GIT_USER_NAM GIT_USER_EMAIL GITHUB_ACTIONS VERSION ALIAS PUSH_REMOTE=false
+ENV GIT_USER_NAME=$GIT_USER_NAME GIT_USER_EMAIL=$GIT_USER_EMAIL GITHUB_ACTIONS=$GITHUB_ACTIONS VERSION=$VERSION ALIAS=$ALIAS PUSH_REMOTE=$PUSH_REMOTE
 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
+RUN pip install -r ./docs/requirements.txt
+RUN \
+  if [ "PUSH_REMOTE" = "true" ]; then export MIKE_SET_PUSH_FLAG="--push"; else export MIKE_SET_PUSH_FLAG=""; fi && \
+  mike deploy --update-aliases ${VERSION} ${ALIAS} && \
+  mike set-default ${MIKE_PUSH_FLAG} ${ALIAS} 
+CMD ["sh", "-c"]

docs/assets/dockerfiles.md

@@ -1 +1 @@
-# Dockerfiles
+# Dockerfiles

docs/assets/index.md

@@ -5,16 +5,9 @@
 !!! info
     **Don't see an asset listed?** Create a [feature request](https://github.com/aws-games/cloud-game-development-toolkit/issues/new?assignees=&labels=feature-request&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE) for a new asset or learn [how to contribute new assets to the project below](#Contribute new Assets to the Cloud Game Development Toolkit)
 
-## Packer Templates
-
-Packer templates provide an easy way to build machine images for commonly used game dev infrastructure. Currently the project includes Packer templates for UE5 build agents for Linux and Windows, as well as a Packer template for building a Perforce Helix Core version control AMI.
-
-[Packer Template Documentation](./packer.md)
-
-## Dockerfiles
-
-Dockerfiles for creating Docker images of commonly used game dev infrastructure.
-
-## Contribute new Assets to the Cloud Game Development Toolkit
-
-This section will contain documentation about how to create new assets, how they should be tested and documented, and the process for submitting them as PRs to the project.
+| Asset Type | Description |
+| - | - |
+| [__Packer Templates__](./packer.md) | Packer templates provide an easy way to build machine images for commonly used game dev infrastructure. Currently the project includes Packer templates for UE5 build agents for Linux and Windows, as well as a Packer template for building a Perforce Helix Core version control AMI. |
+| [__Jenkins Pipelines__](./jenkins-pipelines.md) | Jenkins Pipelines for common game dev automation workflows |
+| [__Ansible Playbooks__](./playbooks.md) | Automation scripts for reusable system level configurations. |
+| [__Dockerfiles__](./dockerfiles.md) | Dockerfiles for creating Docker images of commonly used game dev infrastructure. These are primarily used in scenarios where there aren't openly available pre-built images that address a use case, or significant customization is needed that warrants building an image |

docs/requirements.txt

@@ -1,4 +1,5 @@
 # Include required packages for mkdocs
 mkdocs-material==9.5.27
+mkdocs-material-extensions==1.3.1
 mike==2.1.2
 mkdocs-git-revision-date-plugin==0.3.2

mkdocs.yml

@@ -67,7 +67,7 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
-
+      
 nav:
   - Home: 
       - Home: index.md