Generate docs for GitHub Pages (#1379)

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,13 @@
+name: Deploy documentation
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'master'
+jobs:
+  mkdocs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - run: pip install mkdocs mkdocs-material
+    - run: mkdocs gh-deploy

.gitignore

@@ -3,3 +3,4 @@
 .idea
 *version-info.json
 .DS_Store
+site/

Makefile

@@ -86,7 +86,7 @@ transform-al2-to-al2023:
 		hack/transform-al2-to-al2023.sh
 
 .PHONY: lint
-lint: ## Check the source files for syntax and format issues
+lint: lint-docs ## Check the source files for syntax and format issues
 	$(SHFMT_COMMAND) $(SHFMT_FLAGS) --diff $(MAKEFILE_DIR)
 	$(SHELLCHECK_COMMAND) --format gcc --severity error $(SHELL_FILES)
 
@@ -130,7 +130,11 @@ k8s: validate ## Build default K8s version of EKS Optimized AL2 AMI
 .PHONY: 1.27
 1.27: ## Build EKS Optimized AL2 AMI - K8s 1.27
 	$(MAKE) k8s kubernetes_version=1.27.3 kubernetes_build_date=2023-06-30
-
+
+.PHONY: lint-docs
+lint-docs: ## Lint the docs
+	hack/lint-docs.sh
+
 .PHONY: clean
 clean:
 	rm *-manifest.json

README.md

@@ -44,7 +44,7 @@ The Makefile chooses a particular kubelet binary to use per Kubernetes version w
 
 ## 👩‍💻 Using the AMI
 
-The [AMI user guide](doc/USER_GUIDE.md) has details about the AMI's internals, and the [EKS user guide](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami) explains how to use a custom AMI in a managed node group.
+The [AMI user guide](https://awslabs.github.io/amazon-eks-ami/USER_GUIDE/) has details about the AMI's internals, and the [EKS user guide](https://docs.aws.amazon.com/eks/latest/userguide/launch-templates.html#launch-template-custom-ami) explains how to use a custom AMI in a managed node group.
 
 ## 🔒 Security
 

doc/CHANGELOG.md

@@ -0,0 +1 @@
+../CHANGELOG.md

doc/CONTRIBUTING.md

@@ -46,7 +46,7 @@ When submitting PRs, we want to verify that there are no regressions in the AMI
 
 **Test #1: Verify that the unit tests pass**
 
-Please add a test case for your changes, if possible. See the [unit test README](test/README.md) for more information. These tests will be run automatically for every pull request.
+Please add a test case for your changes, if possible. See the [unit test README](https://github.com/awslabs/amazon-eks-ami/tree/master/test#readme) for more information. These tests will be run automatically for every pull request.
 
 ```
 make test

doc/README.md

@@ -0,0 +1 @@
+../README.md

doc/USER_GUIDE.md

@@ -2,23 +2,11 @@
 
 This document includes details about using the AMI template and the resulting AMIs.
 
-1. [AMI template variables](#ami-template-variables)
-1. [Building against other versions of Kubernetes binaries](#building-against-other-versions-of-kubernetes-binaries)
-1. [Providing your own Kubernetes binaries](#providing-your-own-kubernetes-binaries)
-1. [Container image caching](#container-image-caching)
-1. [IAM permissions](#iam-permissions)
-1. [Customizing kubelet config](#customizing-kubelet-config)
-1. [AL2 and Linux kernel information](#al2-and-linux-kernel-information)
-1. [Updating known instance types](#updating-known-instance-types)
-1. [Version-locked packages](#version-locked-packages)
-1. [Image credential provider plugins](#image-credential-provider-plugins)
-1. [Ephemeral Storage](#ephemeral-storage)
-
 ---
 
 ## AMI template variables
 
-Default values for most variables are defined in [a default variable file](eks-worker-al2-variables.json).
+Default values for most variables are defined in [a default variable file](https://github.com/awslabs/amazon-eks-ami/blob/master/eks-worker-al2-variables.json).
 
 Users have the following options for specifying their own values:
 
@@ -310,7 +298,7 @@ If `kernel_version` is not set:
 - For Kubernetes 1.23 and below, `5.4` is used.
 - For Kubernetes 1.24 and above, `5.10` is used.
 
-The [upgrade_kernel.sh script](../scripts/upgrade_kernel.sh) contains the logic for updating and upgrading the kernel.
+The [upgrade_kernel.sh script](https://github.com/awslabs/amazon-eks-ami/blob/master/scripts/upgrade_kernel.sh) contains the logic for updating and upgrading the kernel.
 
 ---
 

hack/lint-docs.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -o errexit
+cd $(dirname $0)
+./generate-template-variable-doc.py
+if ! git diff --exit-code ../doc/USER_GUIDE.md; then
+  echo "ERROR: doc/USER_GUIDE.md is out of date. Please run hack/generate-template-variable-doc.py and commit the changes."
+  exit 1
+fi
+./mkdocs.sh build --strict

hack/mkdocs.Dockerfile

@@ -0,0 +1,4 @@
+FROM python:3.9
+RUN pip install mkdocs mkdocs-material
+WORKDIR /workdir
+ENTRYPOINT ["mkdocs"]

hack/mkdocs.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -o errexit
+
+cd $(dirname $0)
+
+IMAGE_ID=$(docker build --file mkdocs.Dockerfile --quiet .)
+cd ..
+
+if [[ "$*" =~ "serve" ]]; then
+  EXTRA_ARGS="${EXTRA_ARGS} -a 0.0.0.0:8000"
+fi
+
+docker run --rm -v ${PWD}:/workdir -p 8000:8000 ${IMAGE_ID} "${@}" ${EXTRA_ARGS}

mkdocs.yaml

@@ -0,0 +1,19 @@
+site_name: Amazon EKS AMI
+docs_dir: doc/
+site_description: Build template and runtime resources for the Amazon EKS AMI
+repo_name: awslabs/amazon-eks-ami
+repo_url: https://github.com/awslabs/amazon-eks-ami
+nav:
+  - 'Overview': README.md
+  - 'User Guide': USER_GUIDE.md
+  - 'Changelog': CHANGELOG.md
+  - 'Community':
+    - 'Contribution guidelines': CONTRIBUTING.md
+    - 'Code of Conduct': CODE_OF_CONDUCT.md
+
+theme:
+  name: material
+  palette:
+    primary: black
+  features:
+    - navigation.sections