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 c568694837.

* 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

docs/getting-started.md

@@ -0,0 +1,117 @@
+---
+icon: lucide/rocket
+---
+
+# Getting Started
+
+This guide will help you install and configure Adaptive Lighting for the first time.
+
+## Prerequisites
+
+- [Home Assistant](https://www.home-assistant.io/) 2024.12.0 or newer
+- [HACS](https://hacs.xyz/) (Home Assistant Community Store) installed
+
+## Installation
+
+### Via HACS (Recommended)
+
+1. Open HACS in your Home Assistant instance
+2. Click on **Integrations**
+3. Click the **+ Explore & Download Repositories** button
+4. Search for "Adaptive Lighting"
+5. Click **Download**
+6. Restart Home Assistant
+
+Or use this button to open HACS directly:
+
+[![Open your Home Assistant instance and open the Adaptive Lighting integration inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=basnijholt&repository=adaptive-lighting&category=integration)
+
+### Manual Installation
+
+1. Download the latest release from [GitHub](https://github.com/basnijholt/adaptive-lighting/releases)
+2. Extract the `adaptive_lighting` folder to your `config/custom_components/` directory
+3. Restart Home Assistant
+
+## Configuration
+
+### Step 1: Add to configuration.yaml
+
+Add the following to your `configuration.yaml`:
+
+```yaml
+adaptive_lighting:
+```
+
+> [!NOTE]
+> This entry is required even if you plan to configure everything through the UI.
+
+### Step 2: Restart Home Assistant
+
+Restart Home Assistant for the changes to take effect.
+
+### Step 3: Add the Integration
+
+1. Go to **Settings** → **Devices & Services**
+2. Click **+ Add Integration**
+3. Search for "Adaptive Lighting"
+4. Follow the setup wizard to select your lights
+
+### Step 4: Configure Your Lights
+
+You can configure Adaptive Lighting in two ways:
+
+=== "Via UI"
+
+    1. Go to **Settings** → **Devices & Services**
+    2. Find Adaptive Lighting and click **Configure**
+    3. Adjust settings as needed
+
+=== "Via YAML"
+
+    ```yaml
+    adaptive_lighting:
+      - name: "Living Room"
+        lights:
+          - light.living_room_ceiling
+          - light.living_room_lamp
+        min_brightness: 20
+        max_brightness: 100
+        min_color_temp: 2200
+        max_color_temp: 5500
+    ```
+
+## Basic Configuration Example
+
+Here's a simple configuration to get you started:
+
+```yaml
+adaptive_lighting:
+  - name: "Main Lights"
+    lights:
+      - light.living_room
+      - light.bedroom
+      - light.kitchen
+    transition: 30
+    min_brightness: 10
+    max_brightness: 100
+    min_color_temp: 2000
+    max_color_temp: 5500
+```
+
+## Verifying Installation
+
+After configuration, you should see new switches in Home Assistant:
+
+- `switch.adaptive_lighting_main_lights`
+- `switch.adaptive_lighting_sleep_mode_main_lights`
+- `switch.adaptive_lighting_adapt_brightness_main_lights`
+- `switch.adaptive_lighting_adapt_color_main_lights`
+
+Turn on `switch.adaptive_lighting_main_lights` to start adapting your lights!
+
+## Next Steps
+
+- [Configuration Reference](configuration.md) - Explore all available options
+- [Services](services.md) - Learn about service calls for automations
+- [Automation Examples](automation-examples.md) - See real-world automation recipes
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions