Fix broken API references #5372
Conversation
pzich
force-pushed
the
pzich/fix-api-refs
branch
from
bfed8db to
95f9131
Compare
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughDocumentation-only updates adjusting apiref/See Also header paths across multiple component pages. Changes standardize header names, lowercase paths, and point to new/base/device-specific headers. One page (uptime) splits a single API reference into three discrete links. No code logic, behavior, or public API declarations were altered. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
content/components/ota/_index.md (1)
164-164: ota_backend.h reference looks correctMinor nit: consider a human‑readable link label (e.g., “C++ API: ota_backend.h”) instead of repeating the path for better UX.
Apply if desired:
-{{< apiref "ota/ota_backend.h" "ota/ota_backend.h" >}} +{{< apiref "ota/ota_backend.h" "C++ API: ota_backend.h" >}}content/components/output/sm2235.md (1)
135-135: Use a human‑readable link label for apiref.The first apiref argument is shown to readers; avoid exposing the header path.
Apply:
-{{< apiref "sm2235/sm2235.h" "sm2235/sm2235.h" >}} +{{< apiref "API Reference (SM2235)" "sm2235/sm2235.h" >}}content/components/ota/web_server.md (1)
121-121: Prefer a readable label instead of the header path.-{{< apiref "web_server/ota/ota_web_server.h" "web_server/ota/ota_web_server.h" >}} +{{< apiref "API Reference (Web Server OTA)" "web_server/ota/ota_web_server.h" >}}content/components/light/esp32_rmt_led_strip.md (1)
95-95: Align apiref label style with the rest of the docs.-{{< apiref "esp32_rmt_led_strip/led_strip.h" "esp32_rmt_led_strip/led_strip.h" >}} +{{< apiref "API Reference (ESP32 RMT LED Strip)" "esp32_rmt_led_strip/led_strip.h" >}}content/components/weikai.md (1)
299-299: Readable apiref label.-{{< apiref "weikai/weikai.h" "weikai/weikai.h" >}} +{{< apiref "API Reference (WeiKai)" "weikai/weikai.h" >}}content/components/light/hbridge.md (1)
48-48: Readable apiref label.-{{< apiref "hbridge/light/hbridge_light_output.h" "hbridge/light/hbridge_light_output.h" >}} +{{< apiref "API Reference (H‑bridge Light)" "hbridge/light/hbridge_light_output.h" >}}content/components/ota/esphome.md (1)
89-89: Readable apiref label.-{{< apiref "esphome/ota/ota_esphome.h" "esphome/ota/ota_esphome.h" >}} +{{< apiref "API Reference (ESPHome OTA)" "esphome/ota/ota_esphome.h" >}}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (33)
content/components/binary_sensor/ble_presence.md(1 hunks)content/components/button/factory_reset.md(1 hunks)content/components/climate/bedjet.md(1 hunks)content/components/climate/midea.md(1 hunks)content/components/display/pcd8544.md(1 hunks)content/components/display/st7567.md(1 hunks)content/components/display/st7789v.md(1 hunks)content/components/espnow.md(1 hunks)content/components/light/beken_spi_led_strip.md(1 hunks)content/components/light/esp32_rmt_led_strip.md(1 hunks)content/components/light/hbridge.md(1 hunks)content/components/mcp23Sxx.md(1 hunks)content/components/ota/_index.md(1 hunks)content/components/ota/esphome.md(1 hunks)content/components/ota/http_request.md(1 hunks)content/components/ota/web_server.md(1 hunks)content/components/output/sm16716.md(1 hunks)content/components/output/sm2135.md(1 hunks)content/components/output/sm2235.md(1 hunks)content/components/sensor/ade7953.md(1 hunks)content/components/sensor/am43.md(1 hunks)content/components/sensor/bme280.md(1 hunks)content/components/sensor/bmp280.md(1 hunks)content/components/sensor/ens160.md(1 hunks)content/components/sensor/ens210.md(1 hunks)content/components/sensor/max31856.md(1 hunks)content/components/sensor/sdm_meter.md(1 hunks)content/components/sensor/uptime.md(1 hunks)content/components/sn74hc165.md(1 hunks)content/components/tca9555.md(1 hunks)content/components/touchscreen/axs15231.md(1 hunks)content/components/touchscreen/gt911.md(1 hunks)content/components/weikai.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
content/components/tca9555.mdcontent/components/sn74hc165.mdcontent/components/ota/http_request.mdcontent/components/binary_sensor/ble_presence.mdcontent/components/ota/esphome.mdcontent/components/espnow.mdcontent/components/ota/web_server.mdcontent/components/light/hbridge.mdcontent/components/mcp23Sxx.mdcontent/components/output/sm2135.mdcontent/components/output/sm2235.mdcontent/components/sensor/bme280.mdcontent/components/touchscreen/gt911.mdcontent/components/display/st7567.mdcontent/components/sensor/uptime.mdcontent/components/sensor/ens210.mdcontent/components/button/factory_reset.mdcontent/components/display/st7789v.mdcontent/components/touchscreen/axs15231.mdcontent/components/light/esp32_rmt_led_strip.mdcontent/components/sensor/max31856.mdcontent/components/sensor/sdm_meter.mdcontent/components/sensor/am43.mdcontent/components/climate/midea.mdcontent/components/display/pcd8544.mdcontent/components/sensor/ens160.mdcontent/components/sensor/bmp280.mdcontent/components/sensor/ade7953.mdcontent/components/output/sm16716.mdcontent/components/weikai.mdcontent/components/ota/_index.mdcontent/components/light/beken_spi_led_strip.mdcontent/components/climate/bedjet.md
🔇 Additional comments (26)
content/components/sensor/bmp280.md (1)
95-95: Correct switch to bmp280_base headerMatches current structure; proceed after header existence check (see script in sm2135.md comment).
content/components/climate/bedjet.md (1)
214-214: bedjet_hub.h target looks rightGood change; ensure Doxygen generates this symbol on the docs ref used by “current”. Covered by the verification script.
content/components/output/sm16716.md (1)
219-219: apiref now points to sm16716/sm16716.h — OKConsistent with other output components. Verify via the shared script.
content/components/sensor/ens160.md (1)
110-110: Move to ens160_base header — OKBase header reference aligns with recent reorganizations. Validate presence via the shared script.
content/components/sensor/am43.md (1)
67-67: apiref retarget to am43_base.h — looks goodConsistent with base split. Validate with the shared script.
content/components/binary_sensor/ble_presence.md (1)
139-139: Device‑specific header reference LGTMSwitch to ble_presence_device.h makes sense. Covered by the verification script.
content/components/output/sm2135.md (1)
124-124: apiref path update LGTM — headers verified in esphome/esphome (REF=dev)
All listed headers in the check script were found (OK).content/components/sensor/sdm_meter.md (1)
122-122: Approve — apiref corrected to sdm_meter/sdm_meter.hConfirmed header exists at esphome/components/sdm_meter/sdm_meter.h.
content/components/touchscreen/gt911.md (1)
60-60: Approve — apiref relocated to esphome/components/gt911/touchscreen/gt911_touchscreen.h
Header present at esphome/components/gt911/touchscreen/gt911_touchscreen.h.content/components/sensor/ade7953.md (1)
309-309: LGTM — apiref target is correct.
Header found at esphome/components/ade7953_base/ade7953_base.h; approve changes.content/components/sensor/ens210.md (1)
44-44: Approve — apiref lowercased to esphome/components/ens210/ens210.h is correct.
Header found at esphome/components/ens210/ens210.h; no changes required.content/components/espnow.md (1)
217-217: Approve — apiref updated to espnow_component.h. Confirmed file exists at esphome/components/espnow/espnow_component.h.content/components/display/st7567.md (1)
175-175: Approve — apiref updated to st7567_base (verified).
Header exists at esphome/components/st7567_base/st7567_base.h.content/components/sensor/bme280.md (1)
102-102: Apiref now points to bme280_base — OK.
Verified header exists at esphome/components/bme280_base/bme280_base.h.content/components/climate/midea.md (1)
286-286: Approve — apiref switched to midea/air_conditioner.h (verify header exists)
GH API rate-limited and local repo search returned no match for esphome/components/midea/air_conditioner.h; confirm that header exists at esphome/components/midea/air_conditioner.h or update the apiref.content/components/sn74hc165.md (1)
63-63: LGTM: normalized to lowercase path.Matches folder/file casing used elsewhere.
content/components/display/st7789v.md (1)
309-309: LGTM: apiref updated to concrete driver header.Change aligns with component-level header convention.
content/components/sensor/max31856.md (1)
55-55: LGTM: lowercase header path.Consistent with other sensor headers.
content/components/touchscreen/axs15231.md (1)
32-32: LGTM: link now targets touchscreen-specific header.Matches expected subdirectory structure.
content/components/button/factory_reset.md (1)
46-46: LGTM: path reflects new button/ subdirectory.Included in the link-check script noted in pcd8544.md.
content/components/tca9555.md (1)
57-57: LGTM: corrected to lowercase tca9555/tca9555.h.Consistent with I/O expander docs.
content/components/ota/http_request.md (1)
112-112: LGTM: apiref targets backend-specific header.Covered by the verification script provided earlier.
content/components/display/pcd8544.md (1)
63-63: LGTM — apiref points to the correct header variant; automated verification failedRan the provided gh search script; it exited with "/bin/bash: line 10: /dev/fd/63: No such file or directory" and produced no output, so I cannot confirm the referenced headers exist in esphome/esphome. Re-run the check locally or attach the gh search output for confirmation.
content/components/mcp23Sxx.md (1)
146-147: LGTM — paths normalized and labels clear.content/components/sensor/uptime.md (1)
37-39: Split apiref links look good — verification failed; confirm referenced headers existVerification couldn't complete: the verification script returned "gh: Not Found (HTTP 404)". Confirm these files exist under esphome/components:
- uptime/sensor/uptime_seconds_sensor.h
- uptime/sensor/uptime_timestamp_sensor.h
- uptime/text_sensor/uptime_text_sensor.h
Re-run the verification script and paste the command output.
content/components/light/beken_spi_led_strip.md (1)
58-59: Remove orphaned plaintext header path; fix See Also apirefGitHub code search returned 0 matches for "beken_spi_led_strip/led_strip.h" and "beken_spi_led_strip/beken_spi_led_strip.h" — in content/components/light/beken_spi_led_strip.md (lines 58–59) remove the orphaned plaintext line and either correct or remove the {{< apiref "beken_spi_led_strip/led_strip.h" "beken_spi_led_strip/led_strip.h" >}} so See Also doesn't point to a missing header.
| @@ -92,4 +92,4 @@ please consider adding support to the codebase and add it to the list above. | |||
|
|
|||
| - {{< docref "/components/light" >}} | |||
| - {{< docref "/components/power_supply" >}} | |||
| - {{< apiref "esp32_rmt_led_strip/esp32_rmt_led_strip.h" "esp32_rmt_led_strip/esp32_rmt_led_strip.h" >}} | |||
| - {{< apiref "esp32_rmt_led_strip/led_strip.h" "esp32_rmt_led_strip/led_strip.h" >}} | |||
There was a problem hiding this comment.
Hmm, something still seems to be going wrong with apiref
In this case, the resulting URL is
https://api-docs.esphome.io/led__strip_8h (just led_strip.h)
instead of
https://api-docs.esphome.io/esp32__rmt__led__strip_2led__strip_8h (esp32_rmt_led_strip/led_strip.h)
|
Moving this to draft while discussing how best to proceed with this (thread) |
pzich
force-pushed
the
pzich/fix-api-refs
branch
2 times, most recently
from
f5c4d6f to
8605988
Compare
pzich
force-pushed
the
pzich/fix-api-refs
branch
from
8605988 to
f2f7936
Compare
![esphome[bot]](https://avatars.githubusercontent.com/in/247347?s=60&v=4){kind=small}
There was a problem hiding this comment.
As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Description:
Using a horrible bash script, I found a bunch of places where API Reference links lead to a 404.
Note: This fixes most of them, however there are some cases where
apirefdoes not currently work (see thread) but these should all work after esphome/esphome#10794 and #5387 merge.Related issue (if applicable): N/A
Pull request in esphome with YAML changes (if applicable):
N/A
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.