Skip to content

Commit f9ccc94

Browse files
basnijholtbasnijholt
authored
Migrate to markdown-code-runner's built-in include_section() (#1417)
1 parent 74a795d commit f9ccc94

File tree

11 files changed

+24
-78
lines changed

11 files changed

+24
-78
lines changed

‎custom_components/adaptive_lighting/docs_gen.py‎

Lines changed: 2 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,12 @@
11
"""Documentation generation utilities for Adaptive Lighting.
22
3-
Provides functions to extract sections from README.md and transform
4-
content for the documentation site. Used by markdown-code-runner
5-
to generate documentation pages from README content.
3+
Provides functions to transform content for the documentation site.
4+
Used by markdown-code-runner to generate documentation pages from README content.
65
"""
76

87
from __future__ import annotations
98

109
import re
11-
from pathlib import Path
12-
13-
# Path to README relative to this module
14-
_MODULE_DIR = Path(__file__).parent
15-
README_PATH = _MODULE_DIR.parent.parent / "README.md"
16-
17-
18-
def readme_section(section_name: str, *, strip_heading: bool = True) -> str:
19-
"""Extract a marked section from README.md.
20-
21-
Sections are marked with HTML comments:
22-
<!-- SECTION:section_name:START -->
23-
content
24-
<!-- SECTION:section_name:END -->
25-
26-
Args:
27-
section_name: The name of the section to extract
28-
strip_heading: If True, remove the first heading from the section
29-
30-
Returns:
31-
The content between the section markers
32-
33-
Raises:
34-
ValueError: If the section is not found in README.md
35-
36-
"""
37-
content = README_PATH.read_text()
38-
39-
start_marker = f"<!-- SECTION:{section_name}:START -->"
40-
end_marker = f"<!-- SECTION:{section_name}:END -->"
41-
42-
start_idx = content.find(start_marker)
43-
if start_idx == -1:
44-
msg = f"Section '{section_name}' not found in README.md"
45-
raise ValueError(msg)
46-
47-
end_idx = content.find(end_marker, start_idx)
48-
if end_idx == -1:
49-
msg = f"End marker for section '{section_name}' not found"
50-
raise ValueError(msg)
51-
52-
section = content[start_idx + len(start_marker) : end_idx].strip()
53-
54-
if strip_heading:
55-
# Remove first heading (# or ## or ###)
56-
section = re.sub(r"^#{1,3}\s+[^\n]+\n+", "", section, count=1)
57-
58-
return _transform_readme_links(section)
5910

6011

6112
def _transform_readme_links(content: str) -> str:

‎docs/advanced/brightness-modes.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,7 @@ Adaptive Lighting supports three brightness modes:
1919
## Detailed Explanation
2020

2121
<!-- CODE:START -->
22-
<!-- from adaptive_lighting.docs_gen import readme_section -->
23-
<!-- print(readme_section("brightness-modes")) -->
22+
<!-- print(include_section("../../README.md", "brightness-modes", strip_heading=True)) -->
2423
<!-- CODE:END -->
2524
<!-- OUTPUT:START -->
2625
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
@@ -90,8 +89,7 @@ adaptive_lighting:
9089
These graphs show how brightness changes throughout the day based on calculated values:
9190
9291
<!-- CODE:START -->
93-
<!-- from adaptive_lighting.docs_gen import readme_section -->
94-
<!-- print(readme_section("graphs")) -->
92+
<!-- print(include_section("../../README.md", "graphs", strip_heading=True)) -->
9593
<!-- CODE:END -->
9694
<!-- OUTPUT:START -->
9795
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/advanced/manual-control.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@ Adaptive Lighting is designed to work seamlessly with manual adjustments, detect
99
## How It Works
1010

1111
<!-- CODE:START -->
12-
<!-- from adaptive_lighting.docs_gen import readme_section -->
13-
<!-- print(readme_section("manual-control")) -->
12+
<!-- print(include_section("../../README.md", "manual-control", strip_heading=True)) -->
1413
<!-- CODE:END -->
1514
<!-- OUTPUT:START -->
1615
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/automation-examples.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ icon: lucide/bot
77
Real-world automation examples showing how to integrate Adaptive Lighting with your Home Assistant setup.
88

99
<!-- CODE:START -->
10-
<!-- from adaptive_lighting.docs_gen import readme_section -->
11-
<!-- print(readme_section("automation-examples")) -->
10+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
11+
<!-- print(_transform_readme_links(include_section("../README.md", "automation-examples", strip_heading=True))) -->
1212
<!-- CODE:END -->
1313
<!-- OUTPUT:START -->
1414
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/configuration.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,8 +85,8 @@ All configuration options are listed below with their default values. These opti
8585
## Full Configuration Example
8686

8787
<!-- CODE:START -->
88-
<!-- from adaptive_lighting.docs_gen import readme_section -->
89-
<!-- print(readme_section("config-example-full", strip_heading=False)) -->
88+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
89+
<!-- print(_transform_readme_links(include_section("../README.md", "config-example-full"))) -->
9090
<!-- CODE:END -->
9191
<!-- OUTPUT:START -->
9292
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ By automatically adapting the settings of your lights throughout the day, Adapti
2626
## Features
2727

2828
<!-- CODE:START -->
29-
<!-- from adaptive_lighting.docs_gen import readme_section -->
30-
<!-- print(readme_section("features")) -->
29+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
30+
<!-- print(_transform_readme_links(include_section("../README.md", "features", strip_heading=True))) -->
3131
<!-- CODE:END -->
3232
<!-- OUTPUT:START -->
3333
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/see-also.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ Resources, tutorials, and related projects for Adaptive Lighting.
99
## Tutorials & Articles
1010

1111
<!-- CODE:START -->
12-
<!-- from adaptive_lighting.docs_gen import readme_section -->
13-
<!-- print(readme_section("see-also")) -->
12+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
13+
<!-- print(_transform_readme_links(include_section("../README.md", "see-also", strip_heading=True))) -->
1414
<!-- CODE:END -->
1515
<!-- OUTPUT:START -->
1616
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎docs/services.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -112,13 +112,11 @@ data:
112112
## adaptive_lighting.change_switch_settings
113113

114114
<!-- CODE:START -->
115-
<!-- from adaptive_lighting.docs_gen import readme_section -->
116-
<!-- print(readme_section("change-switch-settings")) -->
115+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
116+
<!-- print(_transform_readme_links(include_section("../README.md", "change-switch-settings", strip_heading=True))) -->
117117
<!-- CODE:END -->
118118
<!-- OUTPUT:START -->
119119
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
120-
#### `adaptive_lighting.change_switch_settings`
121-
122120
`adaptive_lighting.change_switch_settings` (new in 1.7.0) Change any of the above configuration options of Adaptive Lighting (such as `sunrise_time` or `prefer_rgb_color`) with a service call directly from your script/automation.
123121

124122
> [!WARNING]

‎docs/troubleshooting.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ This guide covers common issues and their solutions when using Adaptive Lighting
99
## Enable Debug Logging
1010

1111
<!-- CODE:START -->
12-
<!-- from adaptive_lighting.docs_gen import readme_section -->
13-
<!-- print(readme_section("troubleshooting-intro")) -->
12+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
13+
<!-- print(_transform_readme_links(include_section("../README.md", "troubleshooting-intro", strip_heading=True))) -->
1414
<!-- CODE:END -->
1515
<!-- OUTPUT:START -->
1616
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
@@ -30,8 +30,8 @@ After the issue occurs, create a new issue report with the log (`/config/home-as
3030
## Common Problems & Solutions
3131

3232
<!-- CODE:START -->
33-
<!-- from adaptive_lighting.docs_gen import readme_section -->
34-
<!-- print(readme_section("common-problems")) -->
33+
<!-- from adaptive_lighting.docs_gen import _transform_readme_links -->
34+
<!-- print(_transform_readme_links(include_section("../README.md", "common-problems", strip_heading=True))) -->
3535
<!-- CODE:END -->
3636
<!-- OUTPUT:START -->
3737
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ requires-python = ">=3.12"
1414
docs = [
1515
"astral",
1616
"homeassistant",
17-
"markdown-code-runner",
17+
"markdown-code-runner>=2.7.0",
1818
"markdown-gfm-admonition",
1919
"pandas",
2020
"shinylive",

0 commit comments

Comments
 (0)