Prefer the component's own domain page when a docs content match is ambiguous (#2609)

Author: bdraco

script/sync_components.py

@@ -2256,8 +2256,14 @@ def _page_anchor_set(text: str) -> frozenset[str]:
 
 
 def _find_component_section(text: str, component_id: str) -> str | None:
+    """Anchor slug of the section documenting *component_id* inside a docs page."""
+    found = _find_component_section_kinded(text, component_id)
+    return found[0] if found else None
+
+
+def _find_component_section_kinded(text: str, component_id: str) -> tuple[str, bool] | None:
     """
-    Anchor slug of the section documenting *component_id* inside a docs page.
+    ``(slug, from_example)`` of the section documenting *component_id* inside a docs page.
 
     Matched on the first config example naming it (``- platform: <stem>``
     for a dotted id, a top-level ``<id>:`` key otherwise) → the nearest
@@ -2273,11 +2279,11 @@ def _find_component_section(text: str, component_id: str) -> str | None:
     headings, _ = _page_anchor_index(text)
     if m := example.search(body):
         preceding = [slug for start, slug in headings if start <= m.start()]
-        return preceding[-1] if preceding else ""
+        return (preceding[-1] if preceding else ""), True
     names = {stem, stem.replace("_", "-")}
     for _, slug in headings:
         if slug in names:
-            return slug
+            return slug, False
     return None
 
 
@@ -2339,16 +2345,23 @@ def _find_docs_page_by_content(
 
     A config-example match wins and carries the section slug; a component
     documented without one (a supported-platforms table row) matches on an
-    inline ``<stem>`` code span with no slug. Either scan bails unless
-    exactly one page matches.
+    inline ``<stem>`` code span with no slug. Section matches rank
+    config-example pages above stem-heading pages, then narrow an ambiguous
+    set to pages under the component's own domain directory; either scan
+    bails unless exactly one page remains.
     """
-    matches: list[tuple[str, str]] = []
+    example_matches: list[tuple[str, str]] = []
+    heading_matches: list[tuple[str, str]] = []
     for path, text in pages.items():
-        slug = _find_component_section(text, component_id)
-        if slug is not None:
-            matches.append((path, slug))
-            if len(matches) > 1:
-                break
+        found = _find_component_section_kinded(text, component_id)
+        if found is None:
+            continue
+        slug, from_example = found
+        (example_matches if from_example else heading_matches).append((path, slug))
+    matches = example_matches or heading_matches
+    if len(matches) > 1 and "." in component_id:
+        domain = component_id.split(".", 1)[0]
+        matches = [m for m in matches if m[0].split("/", 1)[0] == domain] or matches
     if len(matches) == 1:
         return matches[0]
     # Blockquote mentions are commentary about the component, not its docs.

tests/test_sync_components_docs_url_validation.py

@@ -108,6 +108,39 @@ def test_ambiguous_config_example_yields_no_link() -> None:
     assert _resolve_docs_url("", "weikai", {"a": _WEIKAI_PAGE, "b": _WEIKAI_PAGE}) == ("", None)
 
 
+def test_ambiguous_config_example_prefers_own_domain_page() -> None:
+    pages = {
+        "sensor/xiaomi_ble": _XIAOMI_PAGE,
+        "bk72xx_ble_tracker": _XIAOMI_PAGE,
+        "ln882h_ble_tracker": _XIAOMI_PAGE,
+    }
+    url, anchor = _resolve_docs_url("", "sensor.xiaomi_lywsd03mmc", pages)
+    assert url == "https://esphome.io/components/sensor/xiaomi_ble"
+    assert anchor == ("sensor/xiaomi_ble", "lywsd03mmc")
+
+
+def test_ambiguous_config_example_within_own_domain_yields_no_link() -> None:
+    pages = {"sensor/a": _XIAOMI_PAGE, "sensor/b": _XIAOMI_PAGE}
+    assert _resolve_docs_url("", "sensor.xiaomi_lywsd03mmc", pages) == ("", None)
+
+
+def test_ambiguous_stem_heading_prefers_own_domain_page() -> None:
+    pages = {"sensor/p": "## Foo\n", "light/q": "## Foo\n"}
+    url, anchor = _resolve_docs_url("", "sensor.foo", pages)
+    assert url == "https://esphome.io/components/sensor/p"
+    assert anchor == ("sensor/p", "foo")
+
+
+def test_config_example_outranks_own_domain_stem_heading() -> None:
+    pages = {
+        "sensor/other": "## Xiaomi Lywsd03mmc\n\ntext\n",
+        "ble/real": _XIAOMI_PAGE,
+    }
+    url, anchor = _resolve_docs_url("", "sensor.xiaomi_lywsd03mmc", pages)
+    assert url == "https://esphome.io/components/ble/real"
+    assert anchor == ("ble/real", "lywsd03mmc")
+
+
 def test_undocumented_component_yields_no_link() -> None:
     assert _resolve_docs_url("", "climate.coolix", {"light": ""}) == ("", None)