Add documentation site with Zensical framework (#1385)
* Add documentation site with Zensical framework
Create comprehensive documentation site for adaptive-lighting.nijho.lt:
- Add zensical.toml configuration with Material theme (amber/orange)
- Create docs_gen.py module for extracting README sections via markers
- Add section markers to README.md for content reuse
- Create documentation pages:
- index.md: Home with features overview
- getting-started.md: Installation and quick setup
- configuration.md: Auto-generated config options table
- services.md: Auto-generated service documentation
- automation-examples.md: Real-world automation recipes
- troubleshooting.md: Common issues and solutions
- see-also.md: External resources and links
- advanced/brightness-modes.md: Brightness mode deep dive
- advanced/manual-control.md: Manual control system docs
- advanced/sleep-mode.md: Sleep mode configuration
- Add GitHub Actions workflow for building and deploying to Pages
- Add custom CSS with sun-themed styling
- Add CNAME for custom domain
Uses markdown-code-runner to auto-generate content from code schemas
and extract README sections for single-source documentation.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Remove duplicated content from docs, make pages thin wrappers
- troubleshooting.md: Remove manually written "Additional Tips" section
- automation-examples.md: Remove duplicate "Additional Examples" section
- configuration.md: Remove duplicate "Option Categories" tables
- sleep-mode.md: Simplify to reference main config, remove duplicate examples
- docs_gen.py: Remove unused get_troubleshooting() and get_sleep_mode_intro()
This reduces duplication risk by keeping README as single source of truth.
Docs pages now primarily pull content via markdown-code-runner.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Integrate webapp (simulator) into docs workflow
- Merge deploy-webapp.yml into docs.yml workflow
- Build simulator and place at /simulator/ subdirectory
- Update docs links to use relative paths to simulator
- Remove separate deploy-webapp.yml to avoid conflicts
The combined workflow now:
1. Builds docs with zensical
2. Builds webapp with shinylive
3. Copies webapp to site/simulator/
4. Deploys everything to GitHub Pages
Simulator will be at adaptive-lighting.nijho.lt/simulator/
* Fix pre-commit and CI issues
- Add site_name to zensical.toml (required by MkDocs)
- Fix RET504 in docs_gen.py (unnecessary assignment before return)
- Remove docs/run_markdown_code_runner.py (lint issues, not needed for CI)
* Fix _docs_helpers.py import error in CI
- Add try/except for relative vs absolute imports in _docs_helpers.py
- Remove silent error handling in docs workflow (fail on error)
The relative import fails when markdown-code-runner executes the code
directly via sys.path.insert. The fallback to absolute import fixes this.
* Temporarily enable deployment from feature branch
* Add tabulate dependency for pandas to_markdown()
* Fix theme configuration for proper light/dark mode
- Restructure zensical.toml to match working agent-cli config
- Add three-way palette toggle (system/light/dark)
- Use proper [project.theme] structure
- Simplify extra.css to not override theme colors
- Add Inter font for text, JetBrains Mono for code
* Add Plausible analytics and fix homepage navigation
- Add custom analytics override for plausible.nijho.lt tracking
- Remove hide:navigation from index.md to show menu on homepage
* Remove temporary feature branch deployment settings
Revert to main-only deployment for docs workflow before merging.
* Revert "Remove temporary feature branch deployment settings"
This reverts commit c56869483760051599234b820b3cf44de128901f.
* Add markdown-gfm-admonition for GitHub-style admonitions
The zensical build was failing silently because gfm_admonition extension
was not installed. Add the dependency to pyproject.toml and docs workflow.
* Use uv sync for documentation dependencies
Switch from manual pip installs to uv sync with pyproject.toml for cleaner
dependency management and reproducible builds.
* Fix markdown rendering inside details blocks
Enable md_in_html extension and add markdown="1" attribute to <details>
tags so markdown content inside them is properly rendered.
* Remove emojis from manually written documentation
Keep emojis in auto-generated content from README, but remove from
manually maintained docs in favor of clean text and Material icons.
* Enable attr_list extension for button styling
* Improve pyproject.toml and use GitHub-style admonitions
- Add accurate project metadata (version, authors, classifiers, URLs)
- Organize dependency groups: docs, dev, test
- Add tool configs for ruff, mypy, pytest
- Convert MkDocs-style admonitions (!!! tip) to GitHub-style (> [!TIP])
- Use docs group in CI workflow
* Add homeassistant and ulid-transform as runtime dependencies
Remove speculative test dependencies since tests run inside HA core.
* Simplify docs_gen.py - remove wrapper functions
Use readme_section() directly in docs instead of 10 one-liner wrappers.
Changed default strip_heading to True since that's the common case.
* Populate empty OUTPUT sections with markdown-code-runner
* Add markdown-code-runner workflow for auto-updating docs
- Add docs/run_markdown_code_runner.py script to process all docs
- Add GitHub workflow to run on push/PR and auto-commit changes
* Exclude README.md from markdown-code-runner workflow
README.md contains code blocks that import from
homeassistant.components.adaptive_lighting, which only exists
when running inside Home Assistant core, not in a regular venv.
* Update auto-generated docs
* Use editable install for markdown-code-runner workflow
- Add setuptools.packages.find config pointing to custom_components
- Remove sys.path.insert manipulation from all docs files
- Update imports to use adaptive_lighting.* package paths
- Install package with `uv pip install -e .` in workflow
- Remove deprecated license classifier (PEP 639)
* Consolidate markdown-code-runner into single workflow
- Remove separate markdown-code-runner.yml workflow
- Update update-readme.yml to handle all markdown files (docs + README)
- Rename workflow to "Update auto-generated content"
- Update README imports to use adaptive_lighting package path
* Rename workflow to markdown-code-runner
* Remove accidentally committed files
* Remove redundant markdown-code-runner from docs workflow
* Fix: use uv pip install instead of uv add in CI
* Add webapp deps (astral, shinylive) to docs group
* Remove unused install_dependencies action
* Update to latest action versions (uv@v5, upload-pages-artifact@v4)
* Remove try/except import fallback in _docs_helpers.py
* Restore install_dependencies action (used by pytest)
* Simplify docs workflow: run on all pushes/PRs
* Simplify mcr workflow paths; revert install_dependencies to main
* Remove redundant cp+sed for webapp (file already in repo)
* Fix mcr push: pull --rebase before push
* Fix mcr: checkout PR branch instead of detached HEAD
* Update auto-generated content
* Switch from setuptools to hatch build system
Replace [tool.setuptools.packages.find] with [tool.hatch.build.targets.wheel]
for hatchling compatibility.
* Update auto-generated content
* Move homeassistant deps to docs group
This is a HA custom component, not a pip package. The homeassistant
dependency is only needed for docs building, not as a project dependency.
* Update auto-generated content
* Remove PyPI-only metadata from pyproject.toml
* Remove arbitrary version constraints from dependency groups
* Update auto-generated content
* Remove unused troubleshooting section markers from README
* Remove temporary feature branch settings from docs workflow
* Use GitHub admonition syntax for warning in change_switch_settings section
* Update auto-generated content
2026-01-12 23:39:57 +01:00
|
|
|
# Adaptive Lighting Documentation Site Configuration
|
|
|
|
|
# Built with Zensical - https://zensical.org
|
|
|
|
|
|
|
|
|
|
[project]
|
|
|
|
|
site_name = "Adaptive Lighting"
|
|
|
|
|
site_description = "Automatically adjust brightness and color of lights based on the sun position"
|
|
|
|
|
site_author = "Bas Nijholt"
|
|
|
|
|
site_url = "https://adaptive-lighting.nijho.lt/"
|
|
|
|
|
copyright = "Copyright © 2020-2026 Bas Nijholt"
|
|
|
|
|
|
|
|
|
|
repo_url = "https://github.com/basnijholt/adaptive-lighting"
|
|
|
|
|
repo_name = "GitHub"
|
|
|
|
|
edit_uri = "edit/main/docs"
|
|
|
|
|
|
|
|
|
|
nav = [
|
|
|
|
|
{ "Home" = "index.md" },
|
|
|
|
|
{ "Getting Started" = "getting-started.md" },
|
|
|
|
|
{ "Configuration" = "configuration.md" },
|
|
|
|
|
{ "Services" = "services.md" },
|
|
|
|
|
{ "Automation Examples" = "automation-examples.md" },
|
|
|
|
|
{ "Troubleshooting" = "troubleshooting.md" },
|
|
|
|
|
{ "Advanced" = [
|
|
|
|
|
{ "Brightness Modes" = "advanced/brightness-modes.md" },
|
|
|
|
|
{ "Manual Control" = "advanced/manual-control.md" },
|
|
|
|
|
{ "Sleep Mode" = "advanced/sleep-mode.md" },
|
|
|
|
|
] },
|
|
|
|
|
{ "See Also" = "see-also.md" },
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
[project.theme]
|
|
|
|
|
custom_dir = "docs/overrides"
|
|
|
|
|
language = "en"
|
|
|
|
|
logo = "assets/logo.png"
|
|
|
|
|
|
|
|
|
|
features = [
|
|
|
|
|
"announce.dismiss",
|
|
|
|
|
"content.action.edit",
|
|
|
|
|
"content.action.view",
|
|
|
|
|
"content.code.annotate",
|
|
|
|
|
"content.code.copy",
|
|
|
|
|
"content.code.select",
|
|
|
|
|
"content.footnote.tooltips",
|
|
|
|
|
"content.tabs.link",
|
|
|
|
|
"content.tooltips",
|
|
|
|
|
"navigation.footer",
|
|
|
|
|
"navigation.indexes",
|
|
|
|
|
"navigation.instant",
|
|
|
|
|
"navigation.instant.prefetch",
|
|
|
|
|
"navigation.path",
|
|
|
|
|
"navigation.top",
|
|
|
|
|
"navigation.tracking",
|
|
|
|
|
"search.highlight",
|
|
|
|
|
]
|
|
|
|
|
|
|
|
|
|
# Three-way toggle: system preference -> light -> dark -> system preference
|
|
|
|
|
[[project.theme.palette]]
|
|
|
|
|
media = "(prefers-color-scheme)"
|
|
|
|
|
toggle.icon = "lucide/sun-moon"
|
|
|
|
|
toggle.name = "Switch to light mode"
|
|
|
|
|
|
|
|
|
|
[[project.theme.palette]]
|
|
|
|
|
media = "(prefers-color-scheme: light)"
|
|
|
|
|
scheme = "default"
|
|
|
|
|
primary = "amber"
|
|
|
|
|
accent = "orange"
|
|
|
|
|
toggle.icon = "lucide/sun"
|
|
|
|
|
toggle.name = "Switch to dark mode"
|
|
|
|
|
|
|
|
|
|
[[project.theme.palette]]
|
|
|
|
|
media = "(prefers-color-scheme: dark)"
|
|
|
|
|
scheme = "slate"
|
|
|
|
|
primary = "amber"
|
|
|
|
|
accent = "orange"
|
|
|
|
|
toggle.icon = "lucide/moon-star"
|
|
|
|
|
toggle.name = "Switch to system preference"
|
|
|
|
|
|
|
|
|
|
[project.theme.font]
|
|
|
|
|
text = "Inter"
|
|
|
|
|
code = "JetBrains Mono"
|
|
|
|
|
|
|
|
|
|
[project.theme.icon]
|
|
|
|
|
repo = "lucide/github"
|
|
|
|
|
|
|
|
|
|
[project.extra]
|
|
|
|
|
generator = false
|
|
|
|
|
|
2026-01-12 23:50:55 +01:00
|
|
|
[project.extra.analytics]
|
|
|
|
|
provider = "custom"
|
|
|
|
|
|
Add documentation site with Zensical framework (#1385)
* Add documentation site with Zensical framework
Create comprehensive documentation site for adaptive-lighting.nijho.lt:
- Add zensical.toml configuration with Material theme (amber/orange)
- Create docs_gen.py module for extracting README sections via markers
- Add section markers to README.md for content reuse
- Create documentation pages:
- index.md: Home with features overview
- getting-started.md: Installation and quick setup
- configuration.md: Auto-generated config options table
- services.md: Auto-generated service documentation
- automation-examples.md: Real-world automation recipes
- troubleshooting.md: Common issues and solutions
- see-also.md: External resources and links
- advanced/brightness-modes.md: Brightness mode deep dive
- advanced/manual-control.md: Manual control system docs
- advanced/sleep-mode.md: Sleep mode configuration
- Add GitHub Actions workflow for building and deploying to Pages
- Add custom CSS with sun-themed styling
- Add CNAME for custom domain
Uses markdown-code-runner to auto-generate content from code schemas
and extract README sections for single-source documentation.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Remove duplicated content from docs, make pages thin wrappers
- troubleshooting.md: Remove manually written "Additional Tips" section
- automation-examples.md: Remove duplicate "Additional Examples" section
- configuration.md: Remove duplicate "Option Categories" tables
- sleep-mode.md: Simplify to reference main config, remove duplicate examples
- docs_gen.py: Remove unused get_troubleshooting() and get_sleep_mode_intro()
This reduces duplication risk by keeping README as single source of truth.
Docs pages now primarily pull content via markdown-code-runner.
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Integrate webapp (simulator) into docs workflow
- Merge deploy-webapp.yml into docs.yml workflow
- Build simulator and place at /simulator/ subdirectory
- Update docs links to use relative paths to simulator
- Remove separate deploy-webapp.yml to avoid conflicts
The combined workflow now:
1. Builds docs with zensical
2. Builds webapp with shinylive
3. Copies webapp to site/simulator/
4. Deploys everything to GitHub Pages
Simulator will be at adaptive-lighting.nijho.lt/simulator/
* Fix pre-commit and CI issues
- Add site_name to zensical.toml (required by MkDocs)
- Fix RET504 in docs_gen.py (unnecessary assignment before return)
- Remove docs/run_markdown_code_runner.py (lint issues, not needed for CI)
* Fix _docs_helpers.py import error in CI
- Add try/except for relative vs absolute imports in _docs_helpers.py
- Remove silent error handling in docs workflow (fail on error)
The relative import fails when markdown-code-runner executes the code
directly via sys.path.insert. The fallback to absolute import fixes this.
* Temporarily enable deployment from feature branch
* Add tabulate dependency for pandas to_markdown()
* Fix theme configuration for proper light/dark mode
- Restructure zensical.toml to match working agent-cli config
- Add three-way palette toggle (system/light/dark)
- Use proper [project.theme] structure
- Simplify extra.css to not override theme colors
- Add Inter font for text, JetBrains Mono for code
* Add Plausible analytics and fix homepage navigation
- Add custom analytics override for plausible.nijho.lt tracking
- Remove hide:navigation from index.md to show menu on homepage
* Remove temporary feature branch deployment settings
Revert to main-only deployment for docs workflow before merging.
* Revert "Remove temporary feature branch deployment settings"
This reverts commit c56869483760051599234b820b3cf44de128901f.
* Add markdown-gfm-admonition for GitHub-style admonitions
The zensical build was failing silently because gfm_admonition extension
was not installed. Add the dependency to pyproject.toml and docs workflow.
* Use uv sync for documentation dependencies
Switch from manual pip installs to uv sync with pyproject.toml for cleaner
dependency management and reproducible builds.
* Fix markdown rendering inside details blocks
Enable md_in_html extension and add markdown="1" attribute to <details>
tags so markdown content inside them is properly rendered.
* Remove emojis from manually written documentation
Keep emojis in auto-generated content from README, but remove from
manually maintained docs in favor of clean text and Material icons.
* Enable attr_list extension for button styling
* Improve pyproject.toml and use GitHub-style admonitions
- Add accurate project metadata (version, authors, classifiers, URLs)
- Organize dependency groups: docs, dev, test
- Add tool configs for ruff, mypy, pytest
- Convert MkDocs-style admonitions (!!! tip) to GitHub-style (> [!TIP])
- Use docs group in CI workflow
* Add homeassistant and ulid-transform as runtime dependencies
Remove speculative test dependencies since tests run inside HA core.
* Simplify docs_gen.py - remove wrapper functions
Use readme_section() directly in docs instead of 10 one-liner wrappers.
Changed default strip_heading to True since that's the common case.
* Populate empty OUTPUT sections with markdown-code-runner
* Add markdown-code-runner workflow for auto-updating docs
- Add docs/run_markdown_code_runner.py script to process all docs
- Add GitHub workflow to run on push/PR and auto-commit changes
* Exclude README.md from markdown-code-runner workflow
README.md contains code blocks that import from
homeassistant.components.adaptive_lighting, which only exists
when running inside Home Assistant core, not in a regular venv.
* Update auto-generated docs
* Use editable install for markdown-code-runner workflow
- Add setuptools.packages.find config pointing to custom_components
- Remove sys.path.insert manipulation from all docs files
- Update imports to use adaptive_lighting.* package paths
- Install package with `uv pip install -e .` in workflow
- Remove deprecated license classifier (PEP 639)
* Consolidate markdown-code-runner into single workflow
- Remove separate markdown-code-runner.yml workflow
- Update update-readme.yml to handle all markdown files (docs + README)
- Rename workflow to "Update auto-generated content"
- Update README imports to use adaptive_lighting package path
* Rename workflow to markdown-code-runner
* Remove accidentally committed files
* Remove redundant markdown-code-runner from docs workflow
* Fix: use uv pip install instead of uv add in CI
* Add webapp deps (astral, shinylive) to docs group
* Remove unused install_dependencies action
* Update to latest action versions (uv@v5, upload-pages-artifact@v4)
* Remove try/except import fallback in _docs_helpers.py
* Restore install_dependencies action (used by pytest)
* Simplify docs workflow: run on all pushes/PRs
* Simplify mcr workflow paths; revert install_dependencies to main
* Remove redundant cp+sed for webapp (file already in repo)
* Fix mcr push: pull --rebase before push
* Fix mcr: checkout PR branch instead of detached HEAD
* Update auto-generated content
* Switch from setuptools to hatch build system
Replace [tool.setuptools.packages.find] with [tool.hatch.build.targets.wheel]
for hatchling compatibility.
* Update auto-generated content
* Move homeassistant deps to docs group
This is a HA custom component, not a pip package. The homeassistant
dependency is only needed for docs building, not as a project dependency.
* Update auto-generated content
* Remove PyPI-only metadata from pyproject.toml
* Remove arbitrary version constraints from dependency groups
* Update auto-generated content
* Remove unused troubleshooting section markers from README
* Remove temporary feature branch settings from docs workflow
* Use GitHub admonition syntax for warning in change_switch_settings section
* Update auto-generated content
2026-01-12 23:39:57 +01:00
|
|
|
[[project.extra.social]]
|
|
|
|
|
icon = "fontawesome/brands/github"
|
|
|
|
|
link = "https://github.com/basnijholt/adaptive-lighting"
|
|
|
|
|
|
|
|
|
|
[[project.extra.social]]
|
|
|
|
|
icon = "fontawesome/brands/discord"
|
|
|
|
|
link = "https://discord.gg/home-assistant"
|
|
|
|
|
|
|
|
|
|
# Enable GitHub-style admonitions (> [!NOTE], > [!TIP], etc.)
|
|
|
|
|
[project.markdown_extensions.gfm_admonition]
|
|
|
|
|
|
|
|
|
|
# Enable markdown inside HTML blocks (e.g., <details>)
|
|
|
|
|
[project.markdown_extensions.md_in_html]
|
|
|
|
|
|
|
|
|
|
# Enable attribute lists for adding CSS classes (e.g., {.md-button})
|
|
|
|
|
[project.markdown_extensions.attr_list]
|
|
|
|
|
|
|
|
|
|
# Enable syntax highlighting for fenced code blocks
|
|
|
|
|
[project.markdown_extensions.pymdownx.highlight]
|
|
|
|
|
anchor_linenums = true
|
|
|
|
|
|
|
|
|
|
[project.markdown_extensions.pymdownx.superfences]
|
|
|
|
|
|
|
|
|
|
# Enable tabs (=== "Tab Name" syntax)
|
|
|
|
|
[project.markdown_extensions.pymdownx.tabbed]
|
|
|
|
|
alternate_style = true
|
|
|
|
|
|
|
|
|
|
# Enable emoji/icon support
|
|
|
|
|
[project.markdown_extensions.pymdownx.emoji]
|
|
|
|
|
emoji_index = "zensical.extensions.emoji.twemoji"
|
|
|
|
|
emoji_generator = "zensical.extensions.emoji.to_svg"
|