Update mkdocs ver & deps ver & build-docs mk

This patch updates the version of mkdocs used to build the docs
as well as versions of the dependencies required by mkdocs. This
patch also introduces two, new Makefile targets, docs-build-python
and docs-build-docker for building the documentation without
serving it.

.gitignore

@@ -1,6 +1,9 @@
 .DS_Store
 .cache
 
+# Mkdocs
+/.site/
+
 # Test output
 cover.out
 cover.out.norace

Makefile

@@ -530,10 +530,28 @@ deploy-local-vcsim: prereqs kustomize-local-vcsim  ## Deploy controller in the c
 ## Documentation
 ## --------------------------------------
 
+.PHONY: docs-build-python
+docs-build-python: ## Build docs w python
+
+# SKIP_PIP_INSTALL is set to true by the GitHub action that verifies the docs
+# can be built successfully since the GitHub action directly installs the deps.
+ifneq (true,$(SKIP_PIP_INSTALL))
+	pip3 install --user -r ./docs/requirements.txt
+endif
+	$$(python3 -m site --user-base)/bin/mkdocs build --clean --config-file mkdocs.yml
+
+.PHONY: docs-build-docker
+docs-build-docker: ## Build docs w Docker
+	docker build -f Dockerfile.docs -t $(IMAGE)-docs:$(IMAGE_TAG) .
+	docker run -it --rm -v "$$(pwd)":/docs --entrypoint /usr/bin/mkdocs \
+	  $(IMAGE)-docs:$(IMAGE_TAG) build --clean --config-file mkdocs.yml
+
+.PHONY: docs-serve-python
 docs-serve-python: ## Serve docs w python
 	pip3 install --user -r ./docs/requirements.txt
 	$$(python3 -m site --user-base)/bin/mkdocs serve
 
+.PHONY: docs-serve-docker
 docs-serve-docker: ## Serve docs w docker
 	docker build -f Dockerfile.docs -t $(IMAGE)-docs:$(IMAGE_TAG) .
 	docker run -it --rm -p 8000:8000 -v "$$(pwd)":/docs $(IMAGE)-docs:$(IMAGE_TAG)

docs/requirements.txt

@@ -1,7 +1,7 @@
 mkdocs >= 1.5.3
-mkdocs-material >= 9.4.2
-pymdown-extensions >= 10.3
-pygments >= 2.16.1
-mkdocs-git-committers-plugin-2 >= 1.2.0
-mkdocs-git-revision-date-localized-plugin >= 1.2.0
+mkdocs-material >= 9.5.3
+pymdown-extensions >= 10.5
+pygments >= 2.17.2
+mkdocs-git-committers-plugin-2 >= 2.2.2
+mkdocs-git-revision-date-localized-plugin >= 1.2.2
 mkdocs-markdownextradata-plugin >= 0.2.5

docs/start/contrib/submit-change.md

@@ -19,6 +19,15 @@ When creating or modifying the project's `README.md` file or any of the document
 
 For example, the below link points to the `Quickstart` page:
 
+<!--
+Please note the following message appears when building the site documentation:
+
+    INFO    -  Doc file 'start/contrib/submit-change.md' contains an absolute link '/start/quick.md', it was left as is. Did you mean '../quick.md'?
+
+The above message may be safely ignored. It is caused by the below, intentional
+error that demonstrates the *incorrect* method for defining links.
+-->
+
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 [/start/quick.md](/start/quick.md)
 

mkdocs.yml

@@ -87,8 +87,8 @@ markdown_extensions:
 - pymdownx.snippets:
     check_paths: true
 - pymdownx.emoji:
-    emoji_index: !!python/name:materialx.emoji.twemoji
-    emoji_generator: !!python/name:materialx.emoji.to_svg
+    emoji_index: !!python/name:material.extensions.emoji.twemoji
+    emoji_generator: !!python/name:material.extensions.emoji.to_svg
     options:
       custom_icons:
       - material/.icons