Dev

.editorconfig

@@ -0,0 +1,14 @@
+# https://editorconfig.org/
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+
+[*.py]
+max_line_length = 80

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'mkdocs_tech_radar/**'
+      - 'pyproject.toml'
+
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'mkdocs_tech_radar/**'
+      - 'pyproject.toml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# Cancel in-progress deployments when a new one is triggered to prevent stuck deployments.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@4959332f0f014c5280e7eac8b70c90cb574c9f9b # v6.6.0
+        with:
+          version: "latest"
+
+      - name: Install dependencies and plugin
+        run: |
+          uv pip install --system --editable .
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
+
+      - name: Build documentation
+        run: |
+          uv run mkdocs build --config-file mkdocs.yml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: ./site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: trailing-whitespace
+        args: ["--markdown-linebreak-ext=md"]
+      - id: detect-private-key
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.8.3
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "pyproject"
+    ]
+}

Makefile

@@ -0,0 +1,110 @@
+.PHONY: help install dev test clean build serve lint format check docs
+
+##@ General
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage: \033[36m\033[0m\n"} /^[a-zA-Z0-9_-]+:.*?##/ { printf "  \033[36m%-26s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+##@ Environment setup
+install:	## Install dependencies using uv
+	uv sync
+
+dev:	## Install development dependencies
+	uv sync --dev
+
+##@ Development
+serve:	## Start the MkDocs development server
+	uv run mkdocs serve
+
+serve-custom:	## Start the MkDocs development server on custom port
+	uv run mkdocs serve --dev-addr 127.0.0.1:8001
+
+build:	## Build the MkDocs site
+	uv run mkdocs build
+
+##@ Package management
+install-pkg:	## Install the package in editable mode
+	uv pip install --editable .
+
+reinstall:	## Uninstall and reinstall the package
+	uv pip uninstall mkdocs-tech-radar -q && uv pip install --editable . -q
+
+##@ Testing
+test:	## Run tests (installs dev dependencies if needed)
+	@uv sync --dev --quiet
+	uv run pytest
+
+test-verbose:	## Run tests with verbose output
+	@uv sync --dev --quiet
+	uv run pytest -v
+
+test-coverage:	## Run tests with coverage report
+	@uv sync --dev --quiet
+	uv run pytest --cov=mkdocs_tech_radar --cov-report=html --cov-report=term
+
+##@ Code quality
+lint:	## Run linting with ruff
+	uv run ruff check .
+
+lint-fix:	## Run linting and fix auto-fixable issues
+	uv run ruff check . --fix
+
+format:	## Format code with ruff
+	uv run ruff format .
+
+format-check:	## Check code formatting without making changes
+	uv run ruff format . --check
+
+check:	## Run all quality checks (lint + format check + test)
+	@uv sync --dev --quiet
+	uv run ruff check .
+	uv run ruff format . --check
+	uv run pytest
+
+##@ Documentation
+docs-build:	## Build documentation
+	uv run mkdocs build
+
+docs-deploy:	## Deploy documentation to GitHub Pages
+	uv run mkdocs gh-deploy
+
+##@ Cleanup
+clean:	## Remove build artifacts and cache
+	rm -rf build/
+	rm -rf dist/
+	rm -rf site/
+	rm -rf *.egg-info/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+clean-venv:	## Remove virtual environment
+	rm -rf .venv
+
+##@ Package building and publishing
+build-package:	## Build the package
+	uv build
+
+publish-test:	## Publish to TestPyPI
+	uv publish --repository testpypi
+
+publish:	## Publish to PyPI
+	uv publish
+
+##@ Dependency management
+update:	## Update dependencies
+	uv sync --upgrade
+
+lock:	## Update lock file
+	uv lock
+
+add:	## Add a new dependency (use: make add PKG=package_name)
+	uv add $(PKG)
+
+add-dev:	## Add a new development dependency (use: make add-dev PKG=package_name)
+	uv add --dev $(PKG)
+
+remove:	## Remove a dependency (use: make remove PKG=package_name)
+	uv remove $(PKG)
+
+##@ Utility
+show:	## Show installed packages
+	uv pip list