Skip to content

Commit 2700187

Browse files
jgelukJacobus Geluk
jgeluk
and
Jacobus Geluk
authored
chore(docs): drop Insiders and consolidate to open Material (#21)
* chore(docs): drop Insiders and consolidate to single mkdocs config - Merge outsiders Mermaid setup into mkdocs.yml (mermaid2 + JS) - Always use mkdocs.yml in Makefile; remove Insiders token logic - Always install open mkdocs-material via Poetry - Remove mkdocs.insiders.yml and mkdocs.outsiders.yml Simplifies builds to free Material and reduces config drift. * chore(build): replace Poetry with uv and PEP 621 deps - Move dependencies to [project.dependencies] and set license file - Remove Poetry/asdf-poetry; install and use uv - Use 'uv venv' + 'uv sync'; run mkdocs via 'uv run' - Drop Poetry from .tool-versions * chore(ci): remove local GH Actions helper script act.sh Remove obsolete local 'act' helper; not used in current workflow. * chore(python): bump to Python 3.13 - Update .tool-versions to 3.13.1 (asdf) - Set requires-python to ">=3.13" in pyproject - Align Makefile fallback var to 3.13 * chore(build): remove pip remnants; show mkdocs via uv in info - Drop unused PIP variables - Info target prints mkdocs version using `uv run` * chore(build): fix System Python detection; CI to Python 3.13 - Use `command -v python3` for SYSTEM_PYTHON on macOS/Linux - Bump actions/setup-python to v5 and 3.13 * chore(build): pin uv venv to Python 3.13 Force `uv venv --python 3.13` to avoid accidental 3.14 picks on hosts with newer system interpreters; keeps env aligned with asdf/CI. * chore(build): make install non-interactive and show correct versions - Reorder docs-install so venv/deps are set up before info - Ensure venv step recreates with Python 3.13 when mismatched - Avoid interactive prompts by setting UV_VENV_CLEAR=1 - Install packages via `uv sync` only * fix(mkdocs): update emoji extensions and kroki options for strict mode - Switch from materialx.emoji.* to material.extensions.emoji.* (Material >=9.4) - Rename kroki options to snake_case (server_url, download_images, download_dir) * fix(kroki): drop removed download_dir option (strict mode) Newer mkdocs-kroki-plugin no longer supports download_dir; rely on server rendering only. * fix(docs): use root-relative include paths in objective/index Ensures mkdocs-include-markdown finds files consistently in strict mode. * fix(docs): resolve strict include and link warnings in process section - Use root-relative include paths for build step summaries - Replace trailing-slash links with explicit .md doc links * fix(docs): root-relative includes and links in plan/index Resolve strict include failure for Envision/Discover/Assess/Train/Chart. * fix(docs): root-relative includes in run/index Resolve strict include failure for run phase pages. * fix(plantuml): replace deprecated 'skinparam handwritten' with '!option' Removes yellow banner advising to use !option handwritten. * style(plantuml): modernize theme (flat, smaller radius, Roboto) - Disable shadows, reduce round corners to 8 - Use Roboto font to match site - Thinner sequence borders - Handwritten already disabled via !option * chore(make): add docs-diagrams-clean and docs-serve-fresh to refresh UML Ensures PlantUML diagrams are regenerated after theme changes. * style(plantuml): force non-handwritten mode in all diagrams; increase font size - Add `!option handwritten false` at top of each .puml - Bump default FontSize to 14 for better readability * fix(plantuml): move '!option handwritten false' before @startuml Ensures PlantUML processes the non-handwritten directive globally. * fix(plantuml): add explicit skinparam handwritten false at top Force both !option and skinparam handwritten false to eliminate wavy edges. * Fix MkDocs warnings and update configuration - Switch PlantUML back to server rendering (avoid CI complexity) - Fix all absolute links to use relative paths with .md extensions - Fix relative links to include proper .md extensions for strict mode - Remove broken links to non-existent dataset.md file - Update Mermaid config to use plugin's javascript option (fix deprecation) - Remove PAT_MKDOCS_INSIDERS references from GitHub workflow - Update GitHub Actions to latest versions (checkout@v4, cache@v4) - Fix all link warnings to ensure clean builds in strict mode * Fix GitHub workflow: install dependencies for PR builds - Remove condition from 'Install all MkDocs dependencies' step so it runs on PRs - This fixes 'uv: command not found' error when building PRs - Build step runs on all branches/PRs to validate changes - Deploy step only runs on main branch after successful build - Add clarifying comments to workflow steps * Add project files: VS Code settings, charter, and uv lock file - Add .vscode/settings.json for Makefile configuration - Add charter/proposed-charter.md for Use Case Tree Workgroup - Add uv.lock for dependency locking * Update asdf action to v3 and improve Makefile asdf detection - Update asdf-vm/actions/install from v2 to v3 - Makefile now checks if asdf is already installed before installing via Homebrew - This avoids duplicate installations and reduces migration warnings in CI * Update asdf action to v4 for asdf 0.16+ support - Upgrade from v3 to v4 which supports asdf >= v0.16.0 - This should eliminate migration notice warnings in CI logs * Add comprehensive caching for asdf tools and uv dependencies - Cache asdf installations (~/.asdf/installs, plugins, shims) based on .tool-versions - Cache uv package cache and Python venv based on uv.lock/pyproject.toml - Remove old main-branch-only cache - Caching now works for all branches and PRs to speed up builds * Fix labeler.yml configuration format - Convert all labels to use proper match object format with 'any:' and 'changed-files:' - Fix mkdocs-infra label that was causing 'unexpected type' error - Consolidate agnos-ai patterns into single 'any:' block * Remove non-existent docs/main.py from labeler config - Fixes 'Expected string' YAML validation error - File doesn't exist in the repository * Remove Node.js as it's no longer used - PlantUML requires Java (already in .tool-versions), not Node.js - No npm packages or Node.js tools are used in the project - All dependencies are Python-based * Remove Java and PlantUML as we use external PlantUML server - PlantUML is configured with render: 'server' using http://www.plantuml.com/plantuml - No local Java or PlantUML binary needed for server-side rendering - This speeds up CI builds by removing unnecessary dependencies * Remove Java from .tool-versions - Already removed from Makefile in previous commit - Completes the removal of Java dependency * Fix labeler.yml format to use correct changed-files structure - Use 'any-glob-to-any-file' key with array of patterns - Fixes 'changed-files section must have valid config structure' error --------- Co-authored-by: Jacobus Geluk <jgeluk@jg2.local>
1 parent 7b2e6f8 commit 2700187

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+1911
-420
lines changed

‎.github/labeler.yml‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,26 @@
11
mkdocs-infra:
2-
- Makefile
3-
- mkdocs.yml
4-
- docs-overrides/
5-
- docs/assets/
6-
- docs/stylesheets/
7-
- docs/main.py
8-
- '*/**/CNAME'
9-
- .tool-versions
10-
- README.md
2+
- changed-files:
3+
any-glob-to-any-file:
4+
- Makefile
5+
- mkdocs.yml
6+
- docs-overrides/**
7+
- docs/assets/**
8+
- docs/stylesheets/**
9+
- '**/CNAME'
10+
- .tool-versions
11+
- README.md
1112

1213
github-actions:
13-
- .github/
14+
- changed-files:
15+
any-glob-to-any-file:
16+
- .github/**
1417

1518
agnos-ai:
16-
- any: ['agnos-*']
17-
- any: ['*-agnos/**/*']
18-
- any: ['*-agnos-ai/**/*']
19+
- changed-files:
20+
any-glob-to-any-file:
21+
- 'agnos-*'
22+
- '*-agnos/**/*'
23+
- '*-agnos-ai/**/*'
1924

2025

2126

‎.github/workflows/docs.yml‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -23,44 +23,53 @@ jobs:
2323
# uses: Homebrew/actions/setup-homebrew@master
2424
-
2525
name: Install Python
26-
uses: actions/setup-python@v4
26+
uses: actions/setup-python@v5
2727
with:
28-
python-version: '3.10.8'
28+
python-version: '3.13'
2929
-
3030
name: Set up Git repository
31-
uses: actions/checkout@v3
31+
uses: actions/checkout@v4
3232
with:
3333
fetch-depth: 0
3434
-
35-
uses: actions/cache@v3
36-
if: ${{ github.ref == 'refs/heads/main' }}
35+
name: Cache asdf installations
36+
uses: actions/cache@v4
37+
with:
38+
path: |
39+
~/.asdf/installs
40+
~/.asdf/plugins
41+
~/.asdf/shims
42+
key: ${{ runner.os }}-asdf-${{ hashFiles('.tool-versions') }}
43+
restore-keys: |
44+
${{ runner.os }}-asdf-
45+
-
46+
name: Cache uv dependencies
47+
uses: actions/cache@v4
3748
with:
38-
key: ${{ github.ref }}
39-
path: .cache
49+
path: |
50+
~/.cache/uv
51+
.venv
52+
key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock', 'pyproject.toml') }}
53+
restore-keys: |
54+
${{ runner.os }}-uv-
4055
-
4156
name: Install asdf & tools
42-
uses: asdf-vm/actions/install@v2
57+
uses: asdf-vm/actions/install@v4
4358
-
4459
name: Install all MkDocs dependencies
45-
if: ${{ github.ref == 'refs/heads/main' }}
46-
env:
47-
PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
4860
run: |
4961
# echo "/home/linuxbrew/.linuxbrew/bin/brew" >> $GITHUB_PATH
5062
make --environment-overrides docs-install-github-actions
5163
-
5264
name: Build Site
53-
# if: ${{ github.ref != 'refs/heads/main' }}
54-
env:
55-
PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
65+
# Build runs on all branches and PRs to validate changes
5666
# run 'docs-build' twice because 'gen_files' doesn't let MkDocs
5767
# pick up on the generated files in the first run
5868
run: |
5969
make --environment-overrides docs-build
6070
make --environment-overrides docs-build
6171
-
6272
name: Deploy Site
73+
# Deploy only runs on main branch after successful build
6374
if: ${{ github.ref == 'refs/heads/main' }}
64-
env:
65-
PAT_MKDOCS_INSIDERS: ${{ secrets.PAT_MKDOCS_INSIDERS }}
6675
run: make --environment-overrides docs-deploy

‎.tool-versions‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1 @@
1-
python 3.10.8
2-
nodejs 17.4.0
3-
java openjdk-18
4-
poetry 1.4.2
1+
python 3.13.1

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"makefile.configureOnOpen": false
3+
}

‎Makefile‎

Lines changed: 52 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,14 @@ else
1111
ifeq ($(YOUR_OS), Linux)
1212
INSTALL_TARGET := install-linux
1313
ifneq ($(wildcard /home/runner/.*),) # this means we're running in Github Actions
14-
PIP := pip
15-
SYSTEM_PYTHON := python3
14+
SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
1615
else
17-
PIP := $(shell asdf where python)/bin/python -m pip
18-
SYSTEM_PYTHON := $(shell asdf where python)/bin/python3
16+
SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
1917
endif
2018
endif
2119
ifeq ($(YOUR_OS), Darwin)
2220
INSTALL_TARGET := install-macos
23-
PIP := $(shell asdf where python)/bin/python -m pip
24-
ifneq (,$(wildcard /usr/local/bin/python3))
25-
SYSTEM_PYTHON := /usr/local/bin/python3
26-
else
27-
SYSTEM_PYTHON := $(shell asdf where python)/bin/python3
28-
endif
21+
SYSTEM_PYTHON := $(shell command -v python3 || echo python3)
2922
endif
3023
endif
3124

@@ -34,27 +27,15 @@ endif
3427
# on windows in a different way. Here we assume you did that yourself in
3528
# the local project's virtualenv directory (./.venv).
3629
#
37-
ifeq ($(OS),Windows_NT)
38-
VENV_POETRY := $(VIRTUAL_ENV)/bin/poetry
39-
VENV_MKDOCS := $(VIRTUAL_ENV)/bin/mkdocs
40-
VENV_PYTHON := $(VIRTUAL_ENV)/bin/python3
41-
else # On mac and linux we have asdf:
42-
VENV_POETRY := $(shell asdf where poetry)/bin/poetry
43-
VENV_MKDOCS := $(VIRTUAL_ENV)/bin/mkdocs
4430
VENV_PYTHON := $(VIRTUAL_ENV)/bin/python3
45-
endif
31+
UV := uv
32+
PYTHON_VERSION := 3.13
4633

47-
PIPENV_DEFAULT_PYTHON_VERSION := 3.11
34+
PIPENV_DEFAULT_PYTHON_VERSION := 3.13
4835
PIPENV_VENV_IN_PROJECT := 1
4936

5037
CURRENT_BRANCH := $(shell git branch --show-current)
51-
PAT_MKDOCS_INSIDERS := $(shell cat $(HOME)/.secrets/PAT_MKDOCS_INSIDERS.txt 2>/dev/null)
52-
ifneq ($(PAT_MKDOCS_INSIDERS),)
5338
MKDOCS_CONFIG_FILE := mkdocs.yml
54-
else
55-
$(info You do not have the $(HOME)/.secrets/PAT_MKDOCS_INSIDERS.txt file so we are using the open source version of MkDocs)
56-
MKDOCS_CONFIG_FILE := mkdocs.outsiders.yml
57-
endif
5839

5940
.PHONY: all
6041
all: docs-build
@@ -63,11 +44,11 @@ all: docs-build
6344
info:
6445
@echo "Git Branch : ${CURRENT_BRANCH}"
6546
@echo "Operating System : ${YOUR_OS}"
66-
@echo "MkDocs : ${VENV_MKDOCS}"
47+
@echo "MkDocs : $$($(UV) run mkdocs --version)"
6748
@echo "MkDocs config file: ${MKDOCS_CONFIG_FILE}"
6849
@echo "System Python : ${SYSTEM_PYTHON} version: $$($(SYSTEM_PYTHON) --version)"
6950
@echo "Virtual Env Python: ${VENV_PYTHON} version: $$($(VENV_PYTHON) --version)"
70-
@echo "Python poetry : ${VENV_POETRY}"
51+
@echo "uv : $$($(UV) --version)"
7152
@echo "install target : ${INSTALL_TARGET}"
7253

7354
.PHONY: clean
@@ -81,10 +62,11 @@ clean:
8162
install: docs-install
8263

8364
.PHONY: docs-install
84-
docs-install: info docs-install-brew docs-install-brew-packages docs-install-python-packages
65+
# Run env setup first so info shows correct versions
66+
docs-install: docs-install-brew docs-install-brew-packages docs-install-python-packages info
8567

8668
.PHONY: docs-install-github-actions
87-
docs-install-github-actions: info docs-install-brew-packages docs-install-python-packages
69+
docs-install-github-actions: docs-install-brew-packages docs-install-python-packages info
8870

8971
.PHONY: docs-install-brew-packages
9072
docs-install-brew-packages:
@@ -96,9 +78,8 @@ docs-install-brew-packages:
9678
@brew upgrade libjpeg 2>/dev/null || brew install libjpeg
9779
@brew upgrade libpng 2>/dev/null || brew install libpng
9880
@brew upgrade zlib 2>/dev/null || brew install zlib
99-
@brew upgrade plantuml 2>/dev/null || brew install plantuml
10081
@brew upgrade graphviz 2>/dev/null || brew install graphviz
101-
@brew upgrade pdm 2>/dev/null || brew install pdm
82+
@brew upgrade uv 2>/dev/null || brew install uv
10283

10384
.PHONY: docs-install-brew
10485
ifeq ($(YOUR_OS), Linux)
@@ -132,92 +113,77 @@ docs-install-brew-macos:
132113
.PHONY: docs-install-asdf
133114
docs-install-asdf: docs-install-brew
134115
@echo "Install the asdf package manager:"
135-
@brew upgrade asdf 2>/dev/null || brew install asdf
116+
@if ! command -v asdf >/dev/null 2>&1; then \
117+
brew upgrade asdf 2>/dev/null || brew install asdf; \
118+
fi
136119
@asdf plugin add python 2>/dev/null || true
137-
@asdf plugin add nodejs 2>/dev/null || true
138-
@asdf plugin add java 2>/dev/null || true
139-
@asdf plugin add poetry https://github.com/asdf-community/asdf-poetry.git 2>/dev/null || true
140120

141121
.PHONY: docs-install-asdf-packages
142122
docs-install-asdf-packages: docs-install-asdf
143123
@echo "Install packages via asdf:"
144124
asdf install
145125

146-
# poetry gets installed via asdf
147-
$(VENV_POETRY): docs-install-asdf-packages
148-
@echo $@
149-
150126
.PHONY: docs-install-python-packages
151127
#ifneq ($(wildcard /home/runner/.*),)
152128
#docs-install-python-packages: docs-install-asdf
153129
#else
154-
docs-install-python-packages: docs-install-asdf-packages docs-install-standard-python-packages docs-install-special-python-packages
130+
docs-install-python-packages: docs-install-asdf-packages docs-install-standard-python-packages
155131
#endif
156132

157133
.PHONY: docs-install-standard-python-packages
158-
docs-install-standard-python-packages: $(VENV_POETRY)
159-
@echo "Install standard python packages via pip:"
160-
$(VENV_POETRY) config virtualenvs.in-project true --local
161-
$(VENV_POETRY) config experimental.system-git-client true --local
162-
163-
.PHONY: docs-install-special-python-packages
164-
docs-install-special-python-packages: docs-install-ekglib docs-install-mkdocs-insider-version-packages
165-
166-
.PHONY: docs-install-ekglib
167-
docs-install-ekglib: $(VENV_POETRY)
168-
@echo "Install ekglib via poetry:"
169-
$(VENV_POETRY) add "git+https://github.com/EKGF/ekglib.git"
170-
171-
.PHONY: docs-install-mkdocs-insider-version-packages
172-
docs-install-mkdocs-insider-version-packages: $(VENV_POETRY)
173-
ifeq ($(PAT_MKDOCS_INSIDERS),)
174-
@echo "Install standard mkdocs python package via poetry:"
175-
@$(VENV_POETRY) add mkdocs-material
176-
else
177-
@if ! cat poetry.lock | grep -q "mkdocs-material-insiders" ; then \
178-
echo "Install special insiders version of mkdocs python package via poetry:" ;\
179-
echo "First remove the public version of mkdocs-material, if it's installed:" ;\
180-
$(VENV_POETRY) remove mkdocs-material || true ;\
181-
echo "Then install the actual insiders version:" ;\
182-
$(VENV_POETRY) add "git+https://$(PAT_MKDOCS_INSIDERS)@github.com/squidfunk/mkdocs-material-insiders.git" ;\
183-
echo "Insider's version of mkdocs-material has been installed successfully!" ;\
134+
docs-install-standard-python-packages: docs-ensure-venv
135+
@echo "Install Python packages via uv:"
136+
$(UV) sync
137+
138+
.PHONY: docs-ensure-venv
139+
docs-ensure-venv:
140+
@echo "Ensure venv (Python $(PYTHON_VERSION)) exists and matches version:"
141+
@if [ ! -d ".venv" ] || ! ./.venv/bin/python3 --version 2>/dev/null | grep -q "$(PYTHON_VERSION)"; then \
142+
echo "Creating/Recreating venv with Python $(PYTHON_VERSION)"; \
143+
UV_VENV_CLEAR=1 $(UV) venv --python $(PYTHON_VERSION) --quiet; \
144+
else \
145+
echo "Existing venv uses correct Python version"; \
184146
fi
185-
endif
186-
187-
$(VENV_MKDOCS): docs-install-python-packages
188-
@if [ -f $(VENV_MKDOCS) ] ; then echo $(VENV_MKDOCS) exists ; exit 0 ; else echo $(VENV_MKDOCS) does not exist ; exit 1 ; fi
189147

190148
.PHONY: docs-build
191-
docs-build: $(VENV_MKDOCS)
192-
$(VENV_MKDOCS) build --config-file $(MKDOCS_CONFIG_FILE)
149+
docs-build: docs-ensure-venv
150+
$(UV) run mkdocs build --config-file $(MKDOCS_CONFIG_FILE)
193151

194152
.PHONY: docs-build-clean
195-
docs-build-clean:
196-
$(VENV_MKDOCS) build --config-file $(MKDOCS_CONFIG_FILE) --clean
153+
docs-build-clean: docs-ensure-venv
154+
$(UV) run mkdocs build --config-file $(MKDOCS_CONFIG_FILE) --clean
197155

198156
.PHONY: docs-serve
199-
docs-serve: $(VENV_MKDOCS)
200-
$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
157+
docs-serve: docs-ensure-venv
158+
$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
159+
160+
.PHONY: docs-diagrams-clean
161+
docs-diagrams-clean:
162+
@echo "Cleaning generated PlantUML diagrams"
163+
@rm -rf docs/diagrams/out 2>/dev/null || true
164+
165+
.PHONY: docs-serve-fresh
166+
docs-serve-fresh: docs-diagrams-clean docs-serve
201167

202168
.PHONY: docs-serve-fast
203-
docs-serve-fast:
204-
$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
169+
docs-serve-fast: docs-ensure-venv
170+
$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --strict
205171

206172
.PHONY: docs-serve-non-strict
207-
docs-serve-non-strict: $(VENV_MKDOCS)
208-
$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload
173+
docs-serve-non-strict: docs-ensure-venv
174+
$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload
209175

210176
.PHONY: docs-serve-debug
211-
docs-serve-debug: $(VENV_MKDOCS)
212-
$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose --strict
177+
docs-serve-debug: docs-ensure-venv
178+
$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose --strict
213179

214180
.PHONY: docs-serve-debug-non-strict
215-
docs-serve-debug-non-strict: $(VENV_MKDOCS)
216-
$(VENV_MKDOCS) serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose
181+
docs-serve-debug-non-strict: docs-ensure-venv
182+
$(UV) run mkdocs serve --config-file $(MKDOCS_CONFIG_FILE) --livereload --verbose
217183

218184
.PHONY: docs-deploy
219-
docs-deploy: $(VENV_MKDOCS)
220-
$(VENV_MKDOCS) gh-deploy --config-file $(MKDOCS_CONFIG_FILE) --verbose
185+
docs-deploy: docs-ensure-venv
186+
$(UV) run mkdocs gh-deploy --config-file $(MKDOCS_CONFIG_FILE) --verbose
221187

222188
.PHONY: docs-sync-from
223189
docs-sync-from: docs-sync-from-ekg-maturity docs-sync-from-ekg-principles

‎act.sh‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

0 commit comments

Comments
 (0)