docs: Add comprehensive documentation with MkDocs and integrate with coverage workflow

.github/copilot-code-review.md

@@ -3,6 +3,7 @@
 This file intentionally contains only the live, minimal checklist. Full authoritative rules are in `.github/copilot-instructions.md` – that document is the single source of truth. Do not duplicate rules here.
 
 ## Minimal Review Checklist
+
 Synchronised with Section 14 of `copilot-instructions.md`.
 
 - [ ] Architecture: No forbidden framework imports in GATT/SIG layer.
@@ -20,4 +21,5 @@ Synchronised with Section 14 of `copilot-instructions.md`.
 If any item cannot be ticked, the PR must not be approved.
 
 ## Reference
+
 See `.github/copilot-instructions.md` for full rationale, workflow, prohibitions, and escalation process.

.github/workflows/README.md

@@ -55,10 +55,10 @@ python -m pylint src/ble_gatt_device/ --exit-zero --score y
 When testing locally or in agent environments, ensure:
 
 1. **Python 3.11+** is available
-2. **Git submodules** are initialized: `git submodule update --init --recursive`
-3. **Package installation** in development mode: `pip install -e ".[dev]"`
-4. **Tool execution** via Python modules: Use `python -m tool_name` instead of direct commands
-5. **Configuration loading**: flake8-pyproject allows flake8 to read from `pyproject.toml`
+1. **Git submodules** are initialized: `git submodule update --init --recursive`
+1. **Package installation** in development mode: `pip install -e ".[dev]"`
+1. **Tool execution** via Python modules: Use `python -m tool_name` instead of direct commands
+1. **Configuration loading**: flake8-pyproject allows flake8 to read from `pyproject.toml`
 
 ### Key Environment Dependencies
 

.github/workflows/copilot-setup-steps.yml

@@ -8,10 +8,15 @@ on:
     paths:
       - .github/workflows/copilot-setup-steps.yml
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
   copilot-setup-steps:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
 
     # Set the permissions to the lowest permissions possible needed for your steps.
     # Copilot will be given its own token for its operations.
@@ -31,8 +36,23 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+
+      - name: Cache system dependencies
+        uses: actions/cache@v4
+        with:
+          path: /var/cache/apt
+          key: ${{ runner.os }}-apt-copilot-${{ hashFiles('scripts/install-deps.sh') }}
+          restore-keys: |
+            ${{ runner.os }}-apt-copilot-
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3-dev
 
-      - name: Install dependencies
+      - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
           # Install dev, test and examples extras so local setup has BLE example libraries

.github/workflows/lint-check.yml

@@ -6,10 +6,15 @@ on:
   pull_request:
     branches: [ main ]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   format:
     name: 'Format Check'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       contents: read
 
@@ -23,13 +28,25 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: "3.12"
+        cache: 'pip'
+        cache-dependency-path: 'pyproject.toml'
+
+    - name: 'Cache system dependencies'
+      uses: actions/cache@v4
+      with:
+        path: /var/cache/apt
+        key: ${{ runner.os }}-apt-lint-${{ hashFiles('scripts/install-deps.sh') }}
+        restore-keys: |
+          ${{ runner.os }}-apt-lint-
 
-    - name: 'Install Dependencies'
+    - name: 'Install system dependencies'
       run: |
-        python -m pip install --upgrade pip
-        # Install system build dependencies to allow building native example libs
         sudo apt-get update
         sudo apt-get install -y build-essential cmake ninja-build pkg-config libdbus-1-dev libglib2.0-dev libudev-dev python3-dev
+
+    - name: 'Install Python dependencies'
+      run: |
+        python -m pip install --upgrade pip
         pip install -e .[dev,test,examples]
 
     - name: 'Check Code Formatting'
@@ -38,6 +55,7 @@ jobs:
   lint:
     name: 'Lint Check'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     permissions:
       contents: read
 
@@ -51,16 +69,26 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: "3.12"
+        cache: 'pip'
+        cache-dependency-path: 'pyproject.toml'
 
-    - name: 'Install Dependencies'
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e ".[dev,test,examples]"
+    - name: 'Cache system dependencies'
+      uses: actions/cache@v4
+      with:
+        path: /var/cache/apt
+        key: ${{ runner.os }}-apt-lint-${{ hashFiles('scripts/install-deps.sh') }}
+        restore-keys: |
+          ${{ runner.os }}-apt-lint-
 
-    - name: 'Install Shellcheck'
+    - name: 'Install system dependencies'
       run: |
         sudo apt-get update
         sudo apt-get install -y shellcheck
 
+    - name: 'Install Python dependencies'
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev,test,examples]"
+
     - name: 'Run Linting Checks'
       run: ./scripts/lint.sh --all

.github/workflows/test-coverage.yml

@@ -6,13 +6,16 @@ on:
   pull_request:
     branches: [ main ]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     permissions:
       contents: read
-      pages: write
-      id-token: write
     strategy:
       matrix:
         python-version: ["3.9", "3.12"]
@@ -27,25 +30,46 @@ jobs:
       uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: 'pyproject.toml'
+
+    - name: Cache system dependencies
+      uses: actions/cache@v4
+      with:
+        path: /var/cache/apt
+        key: ${{ runner.os }}-apt-${{ hashFiles('scripts/install-deps.sh') }}
+        restore-keys: |
+          ${{ runner.os }}-apt-
 
-    - name: Install dependencies
+    - name: Install system dependencies
       run: |
-        python -m pip install --upgrade pip
-        # Install system build dependencies required to build native example libraries
         sudo apt-get update
         sudo apt-get install -y build-essential cmake ninja-build pkg-config libdbus-1-dev libglib2.0-dev libudev-dev python3-dev
-        # Install dev, test and examples extras so CI has the BLE example libraries
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip
         pip install -e .[dev,test,examples]
 
     - name: Run tests with coverage
       run: |
-        python -m pytest tests/ --cov=src/bluetooth_sig --cov-report=html --cov-report=xml --cov-report=term-missing
+        python -m pytest tests/ -n auto --cov=src/bluetooth_sig --cov-report=html --cov-report=xml --cov-report=term-missing --cov-fail-under=70
 
     - name: Extract coverage percentage and create badge
       if: matrix.python-version == '3.12'
       run: |
         python scripts/extract_coverage_badge.py
 
+    - name: Upload test results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: test-results-${{ matrix.python-version }}
+        path: |
+          test-results.xml
+          htmlcov/
+        retention-days: 30
+
     - name: Upload coverage artifacts
       if: matrix.python-version == '3.12'
       uses: actions/upload-artifact@v4
@@ -54,28 +78,85 @@ jobs:
         path: htmlcov
         retention-days: 30
 
+  build-docs:
+    name: Build Documentation
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: 'pyproject.toml'
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+
+      - name: Download coverage artifacts
+        uses: actions/download-artifact@v5
+        with:
+          name: coverage-report
+          path: htmlcov
+        continue-on-error: true
+
+      - name: Link coverage into docs directory
+        run: |
+          if [ -d "htmlcov" ]; then
+            echo "✅ Coverage reports found, linking to docs/"
+            rm -f docs/coverage
+            ln -sf ../htmlcov docs/coverage
+            ls -la docs/coverage | head -3
+          else
+            echo "⚠️  No coverage reports found, docs will build without coverage"
+          fi
+
+      - name: Build documentation
+        run: |
+          mkdocs build
+
+      - name: Upload combined site artifact (main branch only)
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site/
+          retention-days: 30
+
   deploy:
     name: Deploy to GitHub Pages
-    needs: test
+    needs: build-docs
     if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     permissions:
       pages: write
       id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - name: Download coverage artifacts
+      - name: Download site artifacts
         uses: actions/download-artifact@v5
         with:
-          name: coverage-report
-          path: htmlcov
+          name: site
+          path: site
 
       - name: Upload to GitHub Pages
         uses: actions/upload-pages-artifact@v4
         with:
-          path: htmlcov
+          path: site
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -157,6 +157,7 @@ venv.bak/
 
 # mkdocs documentation
 /site
+/docs/supported-characteristics.md
 
 # mypy
 .mypy_cache/
@@ -186,9 +187,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/
 
@@ -209,3 +210,5 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+site/
+docs/coverage