docs: Update MkDocs documentation configuration and dependencies

- Modify mkdocstrings plugin configuration to use default Python handler
- Update documentation requirements to include mkdocstrings-python
- Simplify MkDocs plugin configuration for documentation generation

.github/workflows/deploy-docs.yml

@@ -14,13 +14,21 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
           cache: 'pip'
-      - run: pip install -r docs/requirements.txt
+      - name: Install dependencies
-      - name: Deploy Documentation
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      - name: Configure Git
         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 
+      - name: Build and Deploy
+        run: |
+          mkdocs build --strict
+          mkdocs gh-deploy --force --clean 

docs/requirements.txt

@@ -2,7 +2,8 @@ mkdocs>=1.5.0
 mkdocs-material>=9.0.0
 mkdocs-minify-plugin>=0.7.1
 mkdocs-git-revision-date-plugin>=0.3.2
-mkdocs-mkdocstrings>=0.24.0
+mkdocstrings>=0.24.0
+mkdocstrings-python>=1.0.0
 mkdocs-social-plugin>=0.1.1
 mkdocs-redirects>=1.2.1
 mkdocs-glightbox>=0.3.4

mkdocs.yml

@@ -1,11 +1,23 @@
-site_name: Project Documentation
+site_name: MCP Server for Home Assistant
 site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
 repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
+site_description: Home Assistant MCP Server Documentation
+# Add this to handle GitHub Pages serving from a subdirectory
+site_dir: site/advanced-homeassistant-mcp
 
 theme:
   name: material
   logo: assets/images/logo.png
   favicon: assets/images/favicon.ico
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
   palette:
     - scheme: default
       primary: indigo
@@ -19,18 +31,6 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
-  features:
-    - navigation.instant
-    - navigation.tracking
-    - navigation.sections
-    - navigation.expand
-    - navigation.top
-    - search.suggest
-    - search.highlight
-    - content.code.copy
-    - content.tabs.link
-    - content.tooltips
-    - toc.integrate
 
 markdown_extensions:
   - pymdownx.highlight:
@@ -52,8 +52,7 @@ plugins:
   - minify:
       minify_html: true
   - git-revision-date-plugin
-  - mkdocstrings:
+  - mkdocstrings
-      default_handler: python
   - social
   - tags
   - redirects
@@ -61,8 +60,10 @@ plugins:
 
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md
+  - Getting Started:
-  - API Reference: api.md
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quickstart.md
+  - API Reference: api/index.md
   - Usage: usage.md
   - Configuration:
     - Claude Desktop Config: claude_desktop_config.md