chore(docs): drop Insiders and consolidate to open Material

.github/labeler.yml

@@ -1,21 +1,26 @@
 mkdocs-infra:
-  - Makefile
-  - mkdocs.yml
-  - docs-overrides/
-  - docs/assets/
-  - docs/stylesheets/
-  - docs/main.py
-  - '*/**/CNAME'
-  - .tool-versions
-  - README.md
+  - changed-files:
+      any-glob-to-any-file:
+        - Makefile
+        - mkdocs.yml
+        - docs-overrides/**
+        - docs/assets/**
+        - docs/stylesheets/**
+        - '**/CNAME'
+        - .tool-versions
+        - README.md
 
 github-actions:
-  - .github/
+  - changed-files:
+      any-glob-to-any-file:
+        - .github/**
 
 agnos-ai:
-  - any: ['agnos-*']
-  - any: ['*-agnos/**/*']
-  - any: ['*-agnos-ai/**/*']
+  - changed-files:
+      any-glob-to-any-file:
+        - 'agnos-*'
+        - '*-agnos/**/*'
+        - '*-agnos-ai/**/*'
 
 
 

.github/workflows/docs.yml

@@ -23,44 +23,53 @@ jobs:
 #        uses: Homebrew/actions/setup-homebrew@master
       -
         name: Install Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10.8'
+          python-version: '3.13'
       -
         name: Set up Git repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
       -
-        uses: actions/cache@v3
-        if: ${{ github.ref == 'refs/heads/main' }}
+        name: Cache asdf installations
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.asdf/installs
+            ~/.asdf/plugins
+            ~/.asdf/shims
+          key: ${{ runner.os }}-asdf-${{ hashFiles('.tool-versions') }}
+          restore-keys: |
+            ${{ runner.os }}-asdf-
+      -
+        name: Cache uv dependencies
+        uses: actions/cache@v4
         with:
-          key: ${{ github.ref }}
-          path: .cache
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock', 'pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
       -
         name: Install asdf & tools
-        uses: asdf-vm/actions/install@v2
+        uses: asdf-vm/actions/install@v4
       -
         name: Install all MkDocs dependencies
-        if: ${{ github.ref == 'refs/heads/main' }}
-        env:
-          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
         run: |
           # echo "/home/linuxbrew/.linuxbrew/bin/brew" >> $GITHUB_PATH
           make --environment-overrides docs-install-github-actions
       -
         name: Build Site
-#       if: ${{ github.ref != 'refs/heads/main' }}
-        env:
-          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
+        # Build runs on all branches and PRs to validate changes
         # run 'docs-build' twice because 'gen_files' doesn't let MkDocs 
         # pick up on the generated files in the first run
         run: |
           make --environment-overrides docs-build
           make --environment-overrides docs-build
       -
         name: Deploy Site
+        # Deploy only runs on main branch after successful build
         if: ${{ github.ref == 'refs/heads/main' }}
-        env:
-          PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
         run: make --environment-overrides docs-deploy

.tool-versions

@@ -1,4 +1 @@
-python 3.10.8
-nodejs 17.4.0
-java openjdk-18
-poetry 1.4.2
+python 3.13.1

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

Makefile

@@ -11,21 +11,14 @@ else
 ifeq ($(YOUR_OS), Linux)
 	INSTALL_TARGET := install-linux
 	ifneq ($(wildcard /home/runner/.*),) # this means we're running in Github Actions
-		PIP := pip
-		SYSTEM_PYTHON := python3
+		SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
 	else
-		PIP := $(shell asdf where python)/bin/python -m pip
-		SYSTEM_PYTHON := $(shell asdf where python)/bin/python3
+		SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
 	endif
 endif
 ifeq ($(YOUR_OS), Darwin)
 	INSTALL_TARGET := install-macos
-	PIP := $(shell asdf where python)/bin/python -m pip
-	ifneq (,$(wildcard /usr/local/bin/python3))
-		SYSTEM_PYTHON := /usr/local/bin/python3
-	else
-		SYSTEM_PYTHON := $(shell asdf where python)/bin/python3
-	endif
+	SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
 endif
 endif
 
@@ -34,27 +27,15 @@ endif
 # on windows in a different way. Here we assume you did that yourself in
 # the local project's virtualenv directory (./.venv).
 #
-ifeq ($(OS),Windows_NT)
-VENV_POETRY := $(VIRTUAL_ENV)/bin/poetry
-VENV_MKDOCS := $(VIRTUAL_ENV)/bin/mkdocs
-VENV_PYTHON := $(VIRTUAL_ENV)/bin/python3
-else # On mac and linux we have asdf:
-VENV_POETRY := $(shell asdf where poetry)/bin/poetry
-VENV_MKDOCS := $(VIRTUAL_ENV)/bin/mkdocs
 VENV_PYTHON := $(VIRTUAL_ENV)/bin/python3
-endif
+UV := uv
+PYTHON_VERSION := 3.13
 
-PIPENV_DEFAULT_PYTHON_VERSION := 3.11
+PIPENV_DEFAULT_PYTHON_VERSION := 3.13
 PIPENV_VENV_IN_PROJECT := 1
 
 CURRENT_BRANCH := $(shell git branch --show-current)
-PAT_MKDOCS_INSIDERS := $(shell cat $(HOME)/.secrets/PAT_MKDOCS_INSIDERS.txt 2>/dev/null)
-ifneq ($(PAT_MKDOCS_INSIDERS),)
 MKDOCS_CONFIG_FILE := mkdocs.yml
-else
-$(info You do not have the $(HOME)/.secrets/PAT_MKDOCS_INSIDERS.txt file so we are using the open source version of MkDocs)
-MKDOCS_CONFIG_FILE := mkdocs.outsiders.yml
-endif
 
 .PHONY: all
 all: docs-build
@@ -63,11 +44,11 @@ all: docs-build
 info:
 	@echo "Git Branch        : ${CURRENT_BRANCH}"
 	@echo "Operating System  : ${YOUR_OS}"
-	@echo "MkDocs            : ${VENV_MKDOCS}"
+	@echo "MkDocs            : $$($(UV) run mkdocs --version)"
 	@echo "MkDocs config file: ${MKDOCS_CONFIG_FILE}"
 	@echo "System Python     : ${SYSTEM_PYTHON} version: $$($(SYSTEM_PYTHON) --version)" 
 	@echo "Virtual Env Python: ${VENV_PYTHON} version: $$($(VENV_PYTHON) --version)"
-	@echo "Python poetry     : ${VENV_POETRY}"
+	@echo "uv                : $$($(UV) --version)"
 	@echo "install target    : ${INSTALL_TARGET}"
 
 .PHONY: clean
@@ -81,10 +62,11 @@ clean:
 install: docs-install
 
 .PHONY: docs-install
-docs-install: info docs-install-brew docs-install-brew-packages docs-install-python-packages
+# Run env setup first so info shows correct versions
+docs-install: docs-install-brew docs-install-brew-packages docs-install-python-packages info
 
 .PHONY: docs-install-github-actions
-docs-install-github-actions: info docs-install-brew-packages docs-install-python-packages
+docs-install-github-actions: docs-install-brew-packages docs-install-python-packages info
 
 .PHONY: docs-install-brew-packages
 docs-install-brew-packages:
@@ -96,9 +78,8 @@ docs-install-brew-packages:
 	@brew upgrade libjpeg 2>/dev/null || brew install libjpeg
 	@brew upgrade libpng 2>/dev/null || brew install libpng
 	@brew upgrade zlib 2>/dev/null || brew install zlib
-	@brew upgrade plantuml 2>/dev/null || brew install plantuml
 	@brew upgrade graphviz 2>/dev/null || brew install graphviz
-	@brew upgrade pdm 2>/dev/null || brew install pdm
+	@brew upgrade uv 2>/dev/null || brew install uv
 
 .PHONY: docs-install-brew
 ifeq ($(YOUR_OS), Linux)
@@ -132,92 +113,77 @@ docs-install-brew-macos:
 .PHONY: docs-install-asdf
 docs-install-asdf: docs-install-brew
 	@echo "Install the asdf package manager:"
-	@brew upgrade asdf 2>/dev/null || brew install asdf
+	@if ! command -v asdf >/dev/null 2>&1; then \
+		brew upgrade asdf 2>/dev/null || brew install asdf; \
+	fi
 	@asdf plugin add python 2>/dev/null || true
-	@asdf plugin add nodejs 2>/dev/null || true
-	@asdf plugin add java 2>/dev/null || true
-	@asdf plugin add poetry https://github.com/asdf-community/asdf-poetry.git 2>/dev/null || true
 
 .PHONY: docs-install-asdf-packages
 docs-install-asdf-packages: docs-install-asdf
 	@echo "Install packages via asdf:"
 	asdf install
 
-# poetry gets installed via asdf
-$(VENV_POETRY): docs-install-asdf-packages
-	@echo $@
-
 .PHONY: docs-install-python-packages
 #ifneq ($(wildcard /home/runner/.*),)
 #docs-install-python-packages: docs-install-asdf
 #else
-docs-install-python-packages: docs-install-asdf-packages docs-install-standard-python-packages docs-install-special-python-packages
+docs-install-python-packages: docs-install-asdf-packages docs-install-standard-python-packages
 #endif
 
 .PHONY: docs-install-standard-python-packages
-docs-install-standard-python-packages: $(VENV_POETRY)
-	@echo "Install standard python packages via pip:"
-	$(VENV_POETRY) config virtualenvs.in-project true --local
-	$(VENV_POETRY) config experimental.system-git-client true --local
-
-.PHONY: docs-install-special-python-packages
-docs-install-special-python-packages: docs-install-ekglib docs-install-mkdocs-insider-version-packages
-
-.PHONY: docs-install-ekglib
-docs-install-ekglib: $(VENV_POETRY)
-	@echo "Install ekglib via poetry:"
-	$(VENV_POETRY) add "git+https://github.com/EKGF/ekglib.git"
-
-.PHONY: docs-install-mkdocs-insider-version-packages
-docs-install-mkdocs-insider-version-packages: $(VENV_POETRY)
-ifeq ($(PAT_MKDOCS_INSIDERS),)
-	@echo "Install standard mkdocs python package via poetry:"
-	@$(VENV_POETRY) add mkdocs-material
-else
-	@if ! cat poetry.lock | grep -q "mkdocs-material-insiders" ; then \
-		echo "Install special insiders version of mkdocs python package via poetry:" ;\
-		echo "First remove the public version of mkdocs-material, if it's installed:" ;\
-		$(VENV_POETRY) remove mkdocs-material || true ;\
-		echo "Then install the actual insiders version:" ;\
-		$(VENV_POETRY) add "git+https://$(PAT_MKDOCS_INSIDERS)@github.com/squidfunk/mkdocs-material-insiders.git" ;\
-		echo "Insider's version of mkdocs-material has been installed successfully!" ;\
+docs-install-standard-python-packages: docs-ensure-venv
+	@echo "Install Python packages via uv:"
+	$(UV) sync
+
+.PHONY: docs-ensure-venv
+docs-ensure-venv:
+	@echo "Ensure venv (Python $(PYTHON_VERSION)) exists and matches version:"
+	@if [ ! -d ".venv" ] || ! ./.venv/bin/python3 --version 2>/dev/null | grep -q "$(PYTHON_VERSION)"; then \
+		echo "Creating/Recreating venv with Python $(PYTHON_VERSION)"; \
+		UV_VENV_CLEAR=1 $(UV) venv --python $(PYTHON_VERSION) --quiet; \
+	else \
+		echo "Existing venv uses correct Python version"; \
 	fi
-endif
-
-$(VENV_MKDOCS): docs-install-python-packages
-	@if [ -f $(VENV_MKDOCS) ] ; then echo $(VENV_MKDOCS) exists ; exit 0 ; else echo $(VENV_MKDOCS) does not exist ; exit 1 ; fi
 
 .PHONY: docs-build
-docs-build: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) build --config-file $(MKDOCS_CONFIG_FILE)
+docs-build: docs-ensure-venv
+	$(UV) run mkdocs build --config-file $(MKDOCS_CONFIG_FILE)
 
 .PHONY: docs-build-clean
-docs-build-clean:
-	$(VENV_MKDOCS) build --config-file $(MKDOCS_CONFIG_FILE) --clean
+docs-build-clean: docs-ensure-venv
+	$(UV) run mkdocs build --config-file $(MKDOCS_CONFIG_FILE) --clean
 
 .PHONY: docs-serve
-docs-serve: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
+docs-serve: docs-ensure-venv
+	$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
+
+.PHONY: docs-diagrams-clean
+docs-diagrams-clean:
+	@echo "Cleaning generated PlantUML diagrams"
+	@rm -rf docs/diagrams/out 2>/dev/null || true
+
+.PHONY: docs-serve-fresh
+docs-serve-fresh: docs-diagrams-clean docs-serve
 
 .PHONY: docs-serve-fast
-docs-serve-fast:
-	$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
+docs-serve-fast: docs-ensure-venv
+	$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
 
 .PHONY: docs-serve-non-strict
-docs-serve-non-strict: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload
+docs-serve-non-strict: docs-ensure-venv
+	$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload
 
 .PHONY: docs-serve-debug
-docs-serve-debug: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose --strict
+docs-serve-debug: docs-ensure-venv
+	$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose --strict
 
 .PHONY: docs-serve-debug-non-strict
-docs-serve-debug-non-strict: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose
+docs-serve-debug-non-strict: docs-ensure-venv
+	$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose
 
 .PHONY: docs-deploy
-docs-deploy: $(VENV_MKDOCS)
-	$(VENV_MKDOCS) gh-deploy --config-file $(MKDOCS_CONFIG_FILE) --verbose
+docs-deploy: docs-ensure-venv
+	$(UV) run mkdocs gh-deploy --config-file $(MKDOCS_CONFIG_FILE) --verbose
 
 .PHONY: docs-sync-from
 docs-sync-from: docs-sync-from-ekg-maturity docs-sync-from-ekg-principles