Merge branch 'develop'

Author: Mdevpro78

.gitattributes

@@ -1,15 +1,58 @@
-# Set default behavior to automatically normalize line endings
-* text=auto
-
-# Explicitly declare files that should use LF
-*.sh text eol=lf
-Makefile text eol=lf
-*.mk text eol=lf
-
-# Denote all files that are truly binary and should not be modified
-*.png binary
-*.jpg binary
-*.gif binary
-*.ico binary
-*.zip binary
-*.pdf binary
+# Default: Auto-detect text files and normalize line endings to LF
+* text=auto eol=lf
+
+# Python source files: Enforce UTF‑8 encoding and enable Python-aware diffs
+*.py     text diff=python encoding=utf-8
+*.pyi    text diff=python encoding=utf-8
+*.pyw    text diff=python encoding=utf-8
+
+# Python project configuration files: Consistent UTF‑8 encoding
+*.toml                   text encoding=utf-8
+pyproject.toml           text encoding=utf-8
+requirements*.txt         text encoding=utf-8
+.pre-commit-config.yaml   text encoding=utf-8
+
+# Documentation, configuration, and data files: Uniform encoding and enhanced diffs for Markdown
+*.md   text encoding=utf-8 diff=markdown
+*.rst  text encoding=utf-8
+*.json text encoding=utf-8
+*.yaml text encoding=utf-8
+*.yml  text encoding=utf-8
+*.ini  text encoding=utf-8
+*.cfg  text encoding=utf-8
+
+# Explicitly declare files that should use LF line endings (scripts and makefiles)
+*.sh       text eol=lf
+Makefile   text eol=lf
+*.mk       text eol=lf
+
+# Jupyter Notebooks: Ensure UTF‑8 encoding for proper text processing
+*.ipynb text encoding=utf-8
+
+# Cython source files: Enable proper diffing with enforced UTF‑8 encoding
+*.pyx   text diff=python encoding=utf-8
+
+# Scalable Vector Graphics: Enforce UTF‑8 encoding and enable XML-aware diffs
+*.svg  text encoding=utf-8 diff=xml
+
+# Additional text files: Enforce LF and UTF‑8 for plain text files
+*.txt  text eol=lf working-tree-encoding=utf-8
+
+# Binary and compiled files: Prevent alterations by marking as binary
+*.db     binary
+*.p      binary
+*.pkl    binary
+*.pickle binary
+*.pyc    binary
+*.pyd    binary
+*.pyo    binary
+*.png   binary
+*.jpg   binary
+*.gif   binary
+*.ico   binary
+*.zip   binary
+*.pdf   binary
+
+# Exclude Git-specific files from exports
+.gitattributes export-ignore
+.gitignore     export-ignore

.github/workflows/ci-cd.yml

@@ -0,0 +1,93 @@
+name: Deploy mkdocforge site
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/ci-cd.yml'
+      - 'pyproject.toml'
+      - 'Makefile'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - 'Makefile'
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  lint-docs:
+    name: Lint Documentation
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Setup UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Install linting dependencies
+        run: make uv_sync_lint
+
+      - name: Lint Markdown files
+        run: uv run mdformat --check docs/
+
+  deploy-docs:
+    name: Deploy Documentation
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build-lint
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper versioning
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Setup UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: latest
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          make uv_sync_docs
+
+      - name: Build documentation
+        run: make uv_mkdoc_build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/site.yml

@@ -1,3 +1,4 @@
+---
 # MkDocs-compatible markdownlint configuration
 
 # Default state for all rules

.markdownlint.yaml

@@ -32,5 +32,5 @@ plugin.black.line_length = 88
 
 plugin.ruff.enable = true
 plugin.ruff.line_length = 88
-plugin.ruff.select = ["E", "F", "W"]
-plugin.ruff.ignore = ["ANN101"]
+plugin.ruff.select = [ "E", "F", "W" ]
+plugin.ruff.ignore = [ "ANN101" ]