Chore: Rework documentation layout using mkdocs

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    # We only want to bump versions of packages in case of security updates, as
+    # we want to keep maximum compatibility - see https://t.ly/INSR_
+    open-pull-requests-limit: 0
+    directory: "/"
+    labels: []
+    schedule:
+      interval: weekly
+      time: "08:00"
+  - package-ecosystem: github-actions
+    open-pull-requests-limit: 10
+    directory: "/"
+    labels: []
+    schedule:
+      interval: weekly
+      time: "08:00"

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: tests
+on:
+  pull_request:
+    branches:
+      - main
+
+env:
+  PYTHON_VERSION: 3.x
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+
+      - name: Install dependencies
+        run: make init
+
+      - name: Build documentation with strict mode
+        run: make test

.github/workflows/documentation.yml

@@ -0,0 +1,68 @@
+name: documentation
+on:
+  push:
+    branches:
+      - main
+
+env:
+  PYTHON_VERSION: 3.x
+
+permissions:
+  contents: write
+  id-token: write
+  pages: write
+
+jobs:
+  documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+
+      - name: Install dependencies
+        run: make init
+
+      - name: Build documentation
+        run: make build
+
+      - name: Configure AWS Credentials if S3 deploying is enabled
+        # Giving this step a name so we can check later if we need to deploy to GitHub Pages instead.
+        id: using-s3
+        if: ${{ env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY && env.AWS_S3_BUCKET && env.AWS_REGION }}
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: ${{ secrets.AWS_REGION }}
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
+
+      - name: Push to S3 if enabled
+        if: ${{ steps.using-s3.conclusion == 'success' }}
+        run: aws s3 sync ./site/ s3://${{ secrets.AWS_S3_BUCKET }} --delete
+        env:
+          AWS_REGION: ${{ secrets.AWS_REGION }}
+          AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
+
+      - name: Prepare GitHub Pages artifact if not deploying to S3
+        if: ${{ steps.using-s3.conclusion == 'skipped' }}
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        if: ${{ steps.using-s3.conclusion == 'skipped' }}
+        continue-on-error: true
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,2 +1,5 @@
-.venv
-__pycache__
+.env
+.venv/
+/site/
+/.cache/
+/.idea/

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "GitHub.copilot",
+    "bierner.markdown-mermaid",
+    "esbenp.prettier-vscode",
+    "redhat.vscode-yaml"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Local development",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceRoot}/.venv/bin/mkdocs",
+      "args": ["serve"],
+      "serverReadyAction": {
+        "pattern": "Serving on (https?://.+)",
+        "uriFormat": "%s",
+        "action": "openExternally"
+      }
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,57 @@
+{
+  "editor.tabSize": 4,
+  "editor.formatOnSave": true,
+  "editor.inlineSuggest.enabled": true,
+  "typescript.validate.enable": true,
+  "javascript.validate.enable": true,
+  "[json]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[jsonc]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[css]": {
+    "editor.tabSize": 2
+  },
+  "[scss]": {
+    "editor.tabSize": 2
+  },
+  "[javascript]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascriptreact]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.tabSize": 2,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[html]": {
+    "editor.tabSize": 2
+  },
+  "[markdown]": {
+    "editor.tabSize": 4
+  },
+  "[yaml]": {
+    "editor.tabSize": 2
+  },
+  "[github-actions-workflow]": {
+    "editor.tabSize": 2
+  },
+  // Tabs should be spaces.
+  "editor.insertSpaces": true,
+  "workbench.colorCustomizations": {
+    "titleBar.activeForeground": "#000000",
+    "titleBar.inactiveForeground": "#cccccc",
+    "titleBar.activeBackground": "#ff9925",
+    "titleBar.inactiveBackground": "#341f00"
+  }
+}

Makefile

@@ -0,0 +1,15 @@
+.PHONY: init serve
+SHELL := /bin/bash
+
+init:
+	python3 -m venv .venv
+	source .venv/bin/activate && pip install -r requirements.txt
+
+serve:
+	source .venv/bin/activate && mkdocs serve
+
+build:
+	source .venv/bin/activate && mkdocs build --clean
+
+test:
+	source .venv/bin/activate && mkdocs build --strict --clean