From c4f8ec6e97800c3266fe9279579ca88b7bae566c Mon Sep 17 00:00:00 2001 From: akutz Date: Tue, 26 Dec 2023 09:28:25 -0600 Subject: [PATCH] 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 | 3 +++ Makefile | 18 ++++++++++++++++++ docs/requirements.txt | 10 +++++----- docs/start/contrib/submit-change.md | 9 +++++++++ mkdocs.yml | 4 ++-- 5 files changed, 37 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index 3747e23da..76010dc25 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ .DS_Store .cache +# Mkdocs +/.site/ + # Test output cover.out cover.out.norace diff --git a/Makefile b/Makefile index e641fcc33..114d06a11 100644 --- a/Makefile +++ b/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) diff --git a/docs/requirements.txt b/docs/requirements.txt index 3830a4174..12ddcbdf5 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/start/contrib/submit-change.md b/docs/start/contrib/submit-change.md index dc98e9eb9..f6b52515e 100644 --- a/docs/start/contrib/submit-change.md +++ b/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: + +          [/start/quick.md](/start/quick.md) diff --git a/mkdocs.yml b/mkdocs.yml index 522d64edb..95a11f5d7 100644 --- a/mkdocs.yml +++ b/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