From 4fff318ea9bba0d6578280f56fe06b8e9842aa41 Mon Sep 17 00:00:00 2001 From: jango-blockchained Date: Wed, 5 Feb 2025 21:07:39 +0100 Subject: [PATCH] docs: Enhance documentation deployment and site configuration - Update MkDocs configuration with new features and plugins - Add deployment guide for documentation - Restructure documentation navigation and index page - Create GitHub Actions workflow for automatic documentation deployment - Fix typos in site URLs and configuration --- docs/.github/workflows/deploy-docs.yml | 38 +++++++++ docs/api/index.md | 10 ++- docs/deployment.md | 103 +++++++++++++++++++++++++ docs/getting-started/index.md | 8 ++ docs/index.md | 13 +++- docs/requirements.txt | 1 + mkdocs.yml | 32 +++++--- 7 files changed, 190 insertions(+), 15 deletions(-) create mode 100644 docs/.github/workflows/deploy-docs.yml create mode 100644 docs/deployment.md create mode 100644 docs/getting-started/index.md create mode 100644 docs/requirements.txt diff --git a/docs/.github/workflows/deploy-docs.yml b/docs/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..b9f4e9f --- /dev/null +++ b/docs/.github/workflows/deploy-docs.yml @@ -0,0 +1,38 @@ +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 \ No newline at end of file diff --git a/docs/api/index.md b/docs/api/index.md index 7784abb..65d6ebc 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -231,4 +231,12 @@ The current API version is v1. Include the version in the URL: - [SSE API Details](sse.md) - In-depth SSE documentation - [Core Functions](core.md) - Detailed endpoint documentation - [Architecture Overview](../architecture.md) - System design details -- [Troubleshooting](../troubleshooting.md) - Common issues and solutions \ No newline at end of file +- [Troubleshooting](../troubleshooting.md) - Common issues and solutions + +# API Reference + +The Advanced Home Assistant MCP provides several APIs for integration and automation: + +- [Core API](core-api.md) - Primary interface for system control +- [SSE API](sse.md) - Server-Sent Events for real-time updates +- [Core Functions](core.md) - Essential system functions \ No newline at end of file diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..26c8f07 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,103 @@ +# Deployment Guide + +This documentation is automatically deployed to GitHub Pages using GitHub Actions. Here's how it works and how to manage deployments. + +## Automatic Deployment + +The documentation is automatically deployed when changes are pushed to the `main` or `master` branch. The deployment process: + +1. Triggers on push to main/master +2. Sets up Python environment +3. Installs required dependencies +4. Builds the documentation +5. Deploys to the `gh-pages` branch + +### GitHub Actions Workflow + +The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`: + +```yaml +name: Deploy MkDocs +on: + push: + branches: + - main + - master +``` + +## Manual Deployment + +If needed, you can deploy manually using: + +```bash +# Install dependencies +pip install -r docs/requirements.txt + +# Deploy to GitHub Pages +mkdocs gh-deploy --force +``` + +## Best Practices + +### 1. Documentation Updates +- Test locally before pushing: `mkdocs serve` +- Verify all links work +- Ensure images are optimized +- Check mobile responsiveness + +### 2. Version Control +- Keep documentation in sync with code versions +- Use meaningful commit messages +- Tag important documentation versions + +### 3. Content Guidelines +- Use consistent formatting +- Keep navigation structure logical +- Include examples where appropriate +- Maintain up-to-date screenshots + +### 4. Maintenance +- Regularly review and update content +- Check for broken links +- Update dependencies +- Monitor GitHub Actions logs + +## Troubleshooting + +### Common Issues + +1. **Failed Deployments** + - Check GitHub Actions logs + - Verify dependencies are up to date + - Ensure all required files exist + +2. **Broken Links** + - Run `mkdocs build --strict` + - Use relative paths in markdown + - Check case sensitivity + +3. **Style Issues** + - Verify theme configuration + - Check CSS customizations + - Test on multiple browsers + +## Configuration Files + +### requirements.txt + +Create a requirements file for documentation dependencies: + +```txt +mkdocs-material +mkdocs-minify-plugin +mkdocs-git-revision-date-plugin +mkdocs-mkdocstrings +mkdocs-social-plugin +mkdocs-redirects +``` + +## Monitoring + +- Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages) +- Monitor build status in Actions tab +- Verify site accessibility \ No newline at end of file diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md new file mode 100644 index 0000000..ccb8cdb --- /dev/null +++ b/docs/getting-started/index.md @@ -0,0 +1,8 @@ +# Getting Started + +Welcome to the Advanced Home Assistant MCP getting started guide. Follow these steps to begin: + +1. [Installation](installation.md) +2. [Configuration](configuration.md) +3. [Docker Setup](docker.md) +4. [Quick Start](quickstart.md) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f0e4f5a..e4c34b2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,18 @@ title: Home nav_order: 1 --- -# 🏠 MCP Server for Home Assistant +# Advanced Home Assistant MCP -Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup. +Welcome to the Advanced Home Assistant Master Control Program documentation. + +This documentation provides comprehensive information about setting up, configuring, and using the Advanced Home Assistant MCP system. + +## Quick Links + +- [Getting Started](getting-started/index.md) +- [API Reference](api/index.md) +- [Configuration Guide](getting-started/configuration.md) +- [Docker Setup](getting-started/docker.md) ## What is MCP Server? diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 3fbe865..15208da 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Advanced Home Assistant MCP -site_url: https://jango-blockchained.github.io/advanced-homeassitant-mcp -repo_url: https://github.com/jango-blockchained/advanced-homeassitant-mcp +site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp +repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp theme: name: material @@ -28,6 +28,9 @@ theme: - search.suggest - search.highlight - content.code.copy + - content.tabs.link + - content.tooltips + - toc.integrate markdown_extensions: - pymdownx.highlight: @@ -39,34 +42,38 @@ markdown_extensions: - pymdownx.details - attr_list - md_in_html + - pymdownx.emoji + - pymdownx.tasklist + - footnotes + - tables plugins: - search - - git-revision-date-localized: - type: date + - minify: + minify_html: true + - git-revision-date - mkdocstrings: default_handler: python - handlers: - python: - options: - show_source: true + - social + - tags + - redirects + - gh-deploy nav: - Home: index.md - Usage: usage.md - - API: api.md - Configuration: - Claude Desktop Config: claude_desktop_config.md - - Cline Config: cline_config.md + - Client Config: client_config.md - Getting Started: - - Overview: getting-started.md + - Overview: getting-started/index.md - Installation: getting-started/installation.md - Configuration: getting-started/configuration.md - Docker Setup: getting-started/docker.md - Quick Start: getting-started/quickstart.md - API Reference: - Overview: api/index.md - - Core API: api.md + - Core API: api/core-api.md - SSE API: api/sse.md - Core Functions: api/core.md - Tools: @@ -94,6 +101,7 @@ nav: - Interfaces: development/interfaces.md - Tool Development: development/tools.md - Testing Guide: testing.md + - Deployment Guide: deployment.md - Architecture: architecture.md - Contributing: contributing.md - Troubleshooting: troubleshooting.md