housekeeping

docs/.github/workflows/deploy-docs.yml

@@ -1,38 +0,0 @@
-name: Deploy MkDocs
-on:
-  push:
-    branches:
-      - main
-      - master
-
-permissions:
-  contents: write
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.x'
-      
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install mkdocs-material
-          pip install mkdocs-minify-plugin
-          pip install mkdocs-git-revision-date-plugin
-          pip install mkdocs-mkdocstrings
-          pip install mkdocs-social-plugin
-          pip install mkdocs-redirects
-      
-      - name: Deploy
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          mkdocs gh-deploy --force 

docs/deployment.md

@@ -14,7 +14,7 @@ The documentation is automatically deployed when changes are pushed to the `main
 
 ### GitHub Actions Workflow
 
-The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`:
+The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`. This is the single source of truth for documentation deployment:
 
 ```yaml
 name: Deploy MkDocs
@@ -23,6 +23,7 @@ on:
     branches:
       - main
       - master
+  workflow_dispatch:  # Allow manual trigger
 ```
 
 ## Manual Deployment
@@ -30,9 +31,18 @@ on:
 If needed, you can deploy manually using:
 
 ```bash
+# Create a virtual environment
+python -m venv venv
+
+# Activate the virtual environment
+source venv/bin/activate
+
 # Install dependencies
 pip install -r docs/requirements.txt
 
+# Build the documentation
+mkdocs build
+
 # Deploy to GitHub Pages
 mkdocs gh-deploy --force
 ```
@@ -100,4 +110,32 @@ mkdocs-redirects
 
 - Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages)
 - Monitor build status in Actions tab
-- Verify site accessibility 
+- Verify site accessibility 
+
+## Workflow Features
+
+### Caching
+The workflow implements caching for Python dependencies to speed up deployments:
+- Pip cache for Python packages
+- MkDocs dependencies cache
+
+### Deployment Checks
+Several checks are performed during deployment:
+1. Link validation with `mkdocs build --strict`
+2. Build verification
+3. Post-deployment site accessibility check
+
+### Manual Triggers
+You can manually trigger deployments using the "workflow_dispatch" event in GitHub Actions.
+
+## Cleanup
+
+To clean up duplicate workflow files, run:
+
+```bash
+# Make the script executable
+chmod +x scripts/cleanup-workflows.sh
+
+# Run the cleanup script
+./scripts/cleanup-workflows.sh
+``` 

docs/requirements.txt

@@ -1 +1,9 @@
- 
+mkdocs-material>=9.5.0
+mkdocs-minify-plugin>=0.7.1
+mkdocs-git-revision-date-plugin>=0.3.2
+mkdocs-mkdocstrings>=0.24.0
+mkdocs-social-plugin>=0.1.1
+mkdocs-redirects>=1.2.1
+mkdocs-glightbox>=0.3.4
+pillow>=10.0.0
+cairosvg>=2.7.0