From 7a518845fa7ed92dac48aa014da1c2a23425c0ba Mon Sep 17 00:00:00 2001 From: Matthias Strubel Date: Sat, 20 Jun 2026 08:37:37 +0200 Subject: [PATCH 1/3] docs: add mkdocs-llmstxt plugin to generate llms.txt and llms-full.txt Adds the mkdocs-llmstxt plugin which generates /llms.txt and /llms-full.txt at build time from the existing documentation pages. Both files are served via GitHub Pages and linked from the docs index. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .github/workflows/docs.yml | 2 +- docs/index.md | 5 +++++ mkdocs.yml | 32 ++++++++++++++++++++++++++++++++ pyproject.toml | 1 + 4 files changed, 39 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e8c0ea7f..3e12a225 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,7 +33,7 @@ jobs: python-version: '3.12' - name: Install documentation dependencies - run: pip install "mkdocs-material>=9.5,<10" + run: pip install "mkdocs-material>=9.5,<10" "mkdocs-llmstxt>=0.1.0" - name: Build documentation run: mkdocs build --strict diff --git a/docs/index.md b/docs/index.md index a708f85a..8acde81e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -93,3 +93,8 @@ config/ 📝 **Documentation Status**: This documentation lives in the [`docs/` folder of the batcontrol repository](https://github.com/MaStr/batcontrol/tree/main/docs). If you find outdated information or need additional details, please open an issue or pull request. 🔗 **Project Repository**: [GitHub - Batcontrol](https://github.com/MaStr/batcontrol) + +--- + +**LLM-friendly versions of this documentation:** +[llms.txt](llms.txt) — [llms-full.txt](llms-full.txt) diff --git a/mkdocs.yml b/mkdocs.yml index bf8a5d3d..1bab3703 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,38 @@ markdown_extensions: plugins: - search + - llmstxt: + markdown_description: | + Batcontrol controls a PV battery inverter based on dynamic electricity prices, + solar production forecasts, and consumption patterns. It charges from the grid + when prices are low and preserves stored energy when prices are high. It supports + Fronius Gen24 inverters (HTTP API and Modbus TCP) and any inverter via MQTT bridge. + Tariff providers include Tibber, aWATTar, evcc, EnergyForecast.de, and static zone + tariffs. Solar forecast sources include Forecast.Solar, Solar-Prognose.de, evcc, + and Home Assistant Solar Forecast ML. Peak shaving distributes PV battery charging + across the day using forecasts, and works with both dynamic and static tariffs. + full_output: llms-full.txt + sections: + Getting Started: + - getting-started/installation.md: Installation guide with pre-flight checklist, Docker setup, and next steps + - getting-started/how-batcontrol-works.md: Architecture, control loop, forecasting system, and decision logic + Configuration: + - configuration/batcontrol-configuration.md: Main configuration file reference + - configuration/inverter-configuration.md: Fronius Gen24, Fronius Modbus, and MQTT inverter configuration + - configuration/dynamic-tariff-provider.md: Tibber, aWATTar, evcc, EnergyForecast, and static tariff zones + - configuration/solar-forecast.md: Forecast.Solar, Solar-Prognose.de, evcc, and Home Assistant ML + - configuration/consumption-forecast.md: CSV load profile and Home Assistant API forecast + Features: + - features/peak-shaving.md: Dynamic PV charge rate limiting to maximize solar absorption + - features/battery-control-expert.md: Advanced tuning parameters + - features/price-difference-calculation.md: How price thresholds are calculated + Integrations: + - integrations/mqtt-api.md: MQTT state publishing, runtime overrides, and Home Assistant auto-discovery + - integrations/mqtt-inverter.md: Integrating any battery system via MQTT bridge + - integrations/evcc-connection.md: Coordinating with EV charging via evcc + - integrations/forecast-metrics.md: Forecast data exposed via MQTT + Optional: + - development/15-min-transform.md: Internal 15-minute interval resolution nav: - Home: index.md diff --git a/pyproject.toml b/pyproject.toml index 886d8671..00d63624 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,6 +55,7 @@ test = [ ] docs = [ "mkdocs-material>=9.5,<10", + "mkdocs-llmstxt>=0.1.0", ] # Bump Version From 58581a19b26087426e3acdfdd088b3e0ecca69a5 Mon Sep 17 00:00:00 2001 From: Matthias Strubel Date: Sat, 20 Jun 2026 09:13:56 +0200 Subject: [PATCH 2/3] fix: restrict mkdocs-llmstxt to Python >=3.10 to satisfy uv resolver mkdocs-llmstxt 0.5.0 requires Python >=3.10 but the project declares requires-python >3.8. uv resolves all extras for the full version range, causing the dependency to be unsatisfiable for 3.8/3.9 splits even when only [test] is installed. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 00d63624..31ccfd50 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,7 +55,7 @@ test = [ ] docs = [ "mkdocs-material>=9.5,<10", - "mkdocs-llmstxt>=0.1.0", + "mkdocs-llmstxt>=0.5.0; python_version >= '3.10'", ] # Bump Version From e1cd0c22b5312b0a44834ee88651efbc4cb65de4 Mon Sep 17 00:00:00 2001 From: Matthias Strubel Date: Sat, 20 Jun 2026 09:24:10 +0200 Subject: [PATCH 3/3] fix: address Copilot review comments on llmstxt plugin PR - Add upper version bound <1.0 to mkdocs-llmstxt in pyproject.toml and docs.yml - Use absolute GitHub Pages URLs for llms.txt/llms-full.txt links in index.md to avoid MkDocs strict-mode failures (files are generated post-build and unknown to the link validator) Co-Authored-By: Claude Sonnet 4.6 (1M context) --- .github/workflows/docs.yml | 2 +- docs/index.md | 2 +- pyproject.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3e12a225..76ec3f4a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,7 +33,7 @@ jobs: python-version: '3.12' - name: Install documentation dependencies - run: pip install "mkdocs-material>=9.5,<10" "mkdocs-llmstxt>=0.1.0" + run: pip install "mkdocs-material>=9.5,<10" "mkdocs-llmstxt>=0.5.0,<1.0" - name: Build documentation run: mkdocs build --strict diff --git a/docs/index.md b/docs/index.md index 8acde81e..f62ad205 100644 --- a/docs/index.md +++ b/docs/index.md @@ -97,4 +97,4 @@ config/ --- **LLM-friendly versions of this documentation:** -[llms.txt](llms.txt) — [llms-full.txt](llms-full.txt) +[llms.txt](https://mastr.github.io/batcontrol/llms.txt) — [llms-full.txt](https://mastr.github.io/batcontrol/llms-full.txt) diff --git a/pyproject.toml b/pyproject.toml index 31ccfd50..5294bcd2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,7 +55,7 @@ test = [ ] docs = [ "mkdocs-material>=9.5,<10", - "mkdocs-llmstxt>=0.5.0; python_version >= '3.10'", + "mkdocs-llmstxt>=0.5.0,<1.0; python_version >= '3.10'", ] # Bump Version