Merge pull request #322 from akutz/feature/update-doc-dep-versions

🌱 Update mkdocs ver & deps ver & build-docs mk

.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