alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Enhance MkDocs configuration with advanced features and styling

Browse Source 
- Upgrade MkDocs Material theme with modern navigation and UI features
- Add comprehensive markdown extensions and plugin configurations
- Introduce new JavaScript and CSS for improved documentation experience
- Update documentation requirements with latest plugin versions
- Implement dark mode enhancements and code block improvements
- Expand navigation structure and add new documentation sections
This commit is contained in:
jango-blockchained
2025-02-06 04:00:27 +01:00
parent 2892f24030
commit 6fa88be433
7 changed files with 472 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -31,7 +31,7 @@ wheels/
venv/
ENV/
env/
.venv/
# Logs
logs
*.log
@@ -90,3 +90,5 @@ __pycache__/
*$py.class
models/
*.code-workspace

2
docs/api/index.md
View File

@@ -237,6 +237,6 @@ The current API version is v1. Include the version in the URL:
The Advanced Home Assistant MCP provides several APIs for integration and automation:
- [Core API](core-api.md) - Primary interface for system control
- [Core API](core.md) - Primary interface for system control
- [SSE API](sse.md) - Server-Sent Events for real-time updates
- [Core Functions](core.md) - Essential system functions

62
docs/javascripts/extra.js Normal file
View File

@@ -0,0 +1,62 @@
// Dark mode handling
document.addEventListener('DOMContentLoaded', function () {
// Check for saved dark mode preference
const darkMode = localStorage.getItem('darkMode');
if (darkMode === 'true') {
document.body.classList.add('dark-mode');
}
});
// Smooth scrolling for anchor links
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
anchor.addEventListener('click', function (e) {
e.preventDefault();
document.querySelector(this.getAttribute('href')).scrollIntoView({
behavior: 'smooth'
});
});
});
// Add copy button to code blocks
document.querySelectorAll('pre code').forEach((block) => {
const button = document.createElement('button');
button.className = 'copy-button';
button.textContent = 'Copy';
button.addEventListener('click', async () => {
await navigator.clipboard.writeText(block.textContent);
button.textContent = 'Copied!';
setTimeout(() => {
button.textContent = 'Copy';
}, 2000);
});
const pre = block.parentNode;
pre.insertBefore(button, block);
});
// Add version selector handling
const versionSelector = document.querySelector('.version-selector');
if (versionSelector) {
versionSelector.addEventListener('change', (e) => {
const version = e.target.value;
window.location.href = `/${version}/`;
});
}
// Add feedback handling
document.querySelectorAll('.feedback-button').forEach(button => {
button.addEventListener('click', function () {
const feedback = this.getAttribute('data-feedback');
// Send feedback to analytics
if (typeof gtag !== 'undefined') {
gtag('event', 'feedback', {
'event_category': 'Documentation',
'event_label': feedback
});
}
// Show thank you message
this.textContent = 'Thank you!';
this.disabled = true;
});
});

12
docs/javascripts/mathjax.js Normal file
View File

@@ -0,0 +1,12 @@
window.MathJax = {
tex: {
inlineMath: [["\\(", "\\)"]],
displayMath: [["\\[", "\\]"]],
processEscapes: true,
processEnvironments: true
},
options: {
ignoreHtmlClass: ".*|",
processHtmlClass: "arithmatex"
}
};

53
docs/requirements.txt
View File

@@ -1,12 +1,45 @@
mkdocs>=1.5.0
mkdocs-material>=9.0.0
# Core
mkdocs>=1.5.3
mkdocs-material>=9.5.3
# Enhanced Functionality
mkdocs-minify-plugin>=0.7.1
mkdocstrings>=0.24.0
mkdocstrings-python>=1.0.0
mkdocs-social-plugin==0.1.0
mkdocs-redirects>=1.2.1
mkdocs-git-revision-date-localized-plugin>=1.2.1
mkdocs-glightbox>=0.3.4
pillow>=10.0.0
cairosvg>=2.7.0
pymdown-extensions>=10.0
mkdocs-git-revision-date-plugin
mkdocs-optimize>=0.1.1
mkdocs-git-authors-plugin>=0.7.2
mkdocs-git-committers-plugin>=0.2.3
mkdocs-static-i18n>=1.2.0
mkdocs-awesome-pages-plugin>=2.9.2
mkdocs-redirects>=1.2.1
mkdocs-include-markdown-plugin>=6.0.4
mkdocs-macros-plugin>=1.0.4
mkdocs-meta-descriptions-plugin>=3.0.0
mkdocs-print-site-plugin>=2.3.6
mkdocs-pdf-export-plugin>=0.5.10
mkdocs-with-pdf>=0.9.3
# Code Documentation
mkdocstrings>=0.24.0
mkdocstrings-python>=1.7.5
# Markdown Extensions
pymdown-extensions>=10.5
markdown>=3.5.1
mdx_truly_sane_lists>=1.3
pygments>=2.17.2
# Math Support
python-markdown-math>=0.8
# Diagrams
plantuml-markdown>=3.9.2
mkdocs-mermaid2-plugin>=1.1.1
# Search Enhancements
mkdocs-material[imaging]>=9.5.3
pillow>=10.2.0
cairosvg>=2.7.1
# Development Tools
mike>=2.0.0 # For version management

164
docs/stylesheets/extra.css Normal file
View File

@@ -0,0 +1,164 @@
/* Modern Dark Theme Enhancements */
[data-md-color-scheme="slate"] {
--md-default-bg-color: #1a1b26;
--md-default-fg-color: #a9b1d6;
--md-default-fg-color--light: #a9b1d6;
--md-default-fg-color--lighter: #787c99;
--md-default-fg-color--lightest: #4e5173;
--md-primary-fg-color: #7aa2f7;
--md-primary-fg-color--light: #7dcfff;
--md-primary-fg-color--dark: #2ac3de;
--md-accent-fg-color: #bb9af7;
--md-accent-fg-color--transparent: #bb9af722;
--md-accent-bg-color: #1a1b26;
--md-accent-bg-color--light: #24283b;
}
/* Code Blocks */
.highlight pre {
background-color: #24283b !important;
border-radius: 6px;
padding: 1em;
margin: 1em 0;
overflow: auto;
}
.highlight code {
font-family: 'Roboto Mono', monospace;
font-size: 0.9em;
}
/* Copy Button */
.copy-button {
position: absolute;
right: 0.5em;
top: 0.5em;
padding: 0.4em 0.8em;
background-color: var(--md-accent-bg-color--light);
border: 1px solid var(--md-accent-fg-color--transparent);
border-radius: 4px;
color: var(--md-default-fg-color);
font-size: 0.8em;
cursor: pointer;
transition: all 0.2s ease;
}
.copy-button:hover {
background-color: var(--md-accent-fg-color--transparent);
border-color: var(--md-accent-fg-color);
}
/* Navigation Enhancements */
.md-nav {
font-size: 0.9rem;
}
.md-nav__link {
padding: 0.4rem 0;
transition: color 0.2s ease;
}
.md-nav__link:hover {
color: var(--md-primary-fg-color) !important;
}
/* Tabs */
.md-tabs__link {
opacity: 0.8;
transition: opacity 0.2s ease;
}
.md-tabs__link:hover {
opacity: 1;
}
.md-tabs__link--active {
opacity: 1;
}
/* Admonitions */
.md-typeset .admonition,
.md-typeset details {
border-width: 0;
border-left-width: 4px;
border-radius: 4px;
}
/* Tables */
.md-typeset table:not([class]) {
border-radius: 4px;
box-shadow: 0 2px 4px var(--md-accent-fg-color--transparent);
}
.md-typeset table:not([class]) th {
background-color: var(--md-accent-bg-color--light);
border-bottom: 2px solid var(--md-accent-fg-color--transparent);
}
/* Search */
.md-search__form {
background-color: var(--md-accent-bg-color--light);
border-radius: 4px;
}
/* Feedback Buttons */
.feedback-button {
padding: 0.5em 1em;
margin: 0 0.5em;
border-radius: 4px;
background-color: var(--md-accent-bg-color--light);
border: 1px solid var(--md-accent-fg-color--transparent);
color: var(--md-default-fg-color);
cursor: pointer;
transition: all 0.2s ease;
}
.feedback-button:hover {
background-color: var(--md-accent-fg-color--transparent);
border-color: var(--md-accent-fg-color);
}
.feedback-button:disabled {
opacity: 0.5;
cursor: not-allowed;
}
/* Version Selector */
.version-selector {
padding: 0.5em;
border-radius: 4px;
background-color: var(--md-accent-bg-color--light);
border: 1px solid var(--md-accent-fg-color--transparent);
color: var(--md-default-fg-color);
}
/* Scrollbar */
::-webkit-scrollbar {
width: 8px;
height: 8px;
}
::-webkit-scrollbar-track {
background: var(--md-accent-bg-color--light);
}
::-webkit-scrollbar-thumb {
background: var(--md-accent-fg-color--transparent);
border-radius: 4px;
}
::-webkit-scrollbar-thumb:hover {
background: var(--md-accent-fg-color);
}
/* Print Styles */
@media print {
.md-typeset a {
color: var(--md-default-fg-color) !important;
}
.md-content__inner {
margin: 0;
padding: 1rem;
}
}

233
mkdocs.yml
View File

@@ -9,66 +9,224 @@ theme:
name: material
logo: assets/images/logo.png
favicon: assets/images/favicon.ico
# Modern Features
features:
- navigation.instant
- navigation.tracking
# Navigation Enhancements
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
- navigation.sections
- navigation.expand
- navigation.top
- navigation.path
- navigation.footer
- navigation.prune
- navigation.tracking
- navigation.instant
# UI Elements
- header.autohide
- toc.integrate
- toc.follow
- announce.dismiss
# Search Features
- search.suggest
- search.highlight
- search.share
# Code Features
- content.code.annotate
- content.code.copy
- content.code.select
- content.tabs.link
- content.tooltips
# Theme Configuration
palette:
- scheme: default
primary: indigo
accent: indigo
# Dark mode as primary
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep-purple
accent: purple
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/brightness-4
icon: material/weather-sunny
name: Switch to light mode
# Light mode as secondary
- media: "(prefers-color-scheme: light)"
scheme: default
primary: deep-purple
accent: purple
toggle:
icon: material/weather-night
name: Switch to dark mode
font:
text: Roboto
code: Roboto Mono
icon:
repo: fontawesome/brands/github
edit: material/pencil
view: material/eye
markdown_extensions:
# Modern Code Highlighting
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- admonition
# Advanced Formatting
- pymdownx.critic
- pymdownx.caret
- pymdownx.keys
- pymdownx.mark
- pymdownx.tilde
# Interactive Elements
- pymdownx.details
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tasklist:
custom_checkbox: true
# Diagrams & Formatting
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.arithmatex:
generic: true
# Additional Extensions
- admonition
- attr_list
- md_in_html
- pymdownx.emoji
- pymdownx.tasklist
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- footnotes
- tables
- def_list
- abbr
plugins:
- search
# Core Plugins
- search:
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
- minify:
minify_html: true
- mkdocstrings
- social:
cards: false # Disable social cards if they cause issues
- tags
- redirects
- gh-deploy
- git-revision-date
# Advanced Features
- social:
cards: true
cards_color:
fill: "#1e1e2e"
text: "#cdd6f4"
- tags
- offline
- optimize
# Version Management
- git-revision-date-localized:
enable_creation_date: true
type: date
# Analytics
- analytics:
provider: google
feedback:
title: Was this page helpful?
ratings:
- icon: material/emoticon-happy-outline
name: This page was helpful
data: 1
note: >-
Thanks for your feedback!
- icon: material/emoticon-sad-outline
name: This page could be improved
data: 0
note: >-
Thanks for your feedback!
extra:
# Consent Management
consent:
title: Cookie consent
description: >-
We use cookies to recognize your repeated visits and preferences, as well
as to measure the effectiveness of our documentation and whether users
find what they're searching for. With your consent, you're helping us to
make our documentation better.
actions:
- accept
- reject
- manage
# Version Management
version:
provider: mike
default: latest
# Social Links
social:
- icon: fontawesome/brands/github
link: https://github.com/jango-blockchained/homeassistant-mcp
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
# Status Indicators
status:
new: Recently added
deprecated: Deprecated
beta: Beta
# Analytics
analytics:
provider: google
property: !ENV GOOGLE_ANALYTICS_KEY
feedback:
title: Was this page helpful?
ratings:
- icon: material/emoticon-happy-outline
name: This page was helpful
data: 1
- icon: material/emoticon-sad-outline
name: This page could be improved
data: 0
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/mathjax.js
- https://polyfill.io/v3/polyfill.min.js?features=es6
- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
- javascripts/extra.js
copyright: Copyright © 2025 jango-blockchained
# Keep existing nav structure
nav:
- Home: index.md
- Getting Started:
- Overview: getting-started/index.md
- Installation: getting-started/installation.md
- Quick Start: getting-started/quickstart.md
- API Reference: api/index.md
- Configuration: getting-started/configuration.md
- Docker Setup: getting-started/docker.md
- API Reference:
- Overview: api/index.md
- Core API: api/core.md
- SSE API: api/sse.md
- Usage: usage.md
- Configuration:
- Claude Desktop Config: claude_desktop_config.md
- Client Config: client_config.md
- System Configuration: configuration.md
- Tools:
- Overview: tools/tools.md
- Device Management:
@@ -93,7 +251,8 @@ nav:
- Best Practices: development/best-practices.md
- Interfaces: development/interfaces.md
- Tool Development: development/tools.md
- Testing Guide: testing.md
- Testing Guide: development/test-migration-guide.md
- Testing: testing.md
- Deployment Guide: deployment.md
- Architecture: architecture.md
- Contributing: contributing.md
@@ -101,21 +260,3 @@ nav:
- Examples:
- Overview: examples/index.md
- Roadmap: roadmap.md
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/jango-blockchained/homeassistant-mcp
- icon: fontawesome/brands/docker
link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
analytics:
provider: google
property: !ENV GOOGLE_ANALYTICS_KEY
extra_css:
- stylesheets/extra.css
extra_javascript:
- javascripts/extra.js
copyright: Copyright © 2025 jango-blockchained