From 3007ca4d57de1dce20e05c471a336bffea2f8bb4 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 4 Aug 2025 16:55:46 +1200
Subject: [PATCH] [core] Move docs url generator to helpers.py (#10056)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 esphome/config_validation.py | 12 ++----------
 esphome/helpers.py           | 19 +++++++++++++++++++
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/esphome/config_validation.py b/esphome/config_validation.py
index 84ffd9941e..9aaeb9f9e8 100644
--- a/esphome/config_validation.py
+++ b/esphome/config_validation.py
@@ -87,7 +87,7 @@ from esphome.core import (
     TimePeriodNanoseconds,
     TimePeriodSeconds,
 )
-from esphome.helpers import add_class_to_obj, list_starts_with
+from esphome.helpers import add_class_to_obj, docs_url, list_starts_with
 from esphome.schema_extractors import (
     SCHEMA_EXTRACT,
     schema_extractor,
@@ -666,14 +666,6 @@ def only_with_framework(
     if suggestions is None:
         suggestions = {}
 
-    version = Version.parse(ESPHOME_VERSION)
-    if version.is_beta:
-        docs_format = "https://beta.esphome.io/components/{path}"
-    elif version.is_dev:
-        docs_format = "https://next.esphome.io/components/{path}"
-    else:
-        docs_format = "https://esphome.io/components/{path}"
-
     def validator_(obj):
         if CORE.target_framework not in frameworks:
             err_str = f"This feature is only available with framework(s) {', '.join([framework.value for framework in frameworks])}"
@@ -681,7 +673,7 @@ def only_with_framework(
                 (component, docs_path) = suggestion
                 err_str += f"\nPlease use '{component}'"
                 if docs_path:
-                    err_str += f": {docs_format.format(path=docs_path)}"
+                    err_str += f": {docs_url(path=f'components/{docs_path}')}"
             raise Invalid(err_str)
         return obj
 
diff --git a/esphome/helpers.py b/esphome/helpers.py
index d1f3080e34..f722dc3f7c 100644
--- a/esphome/helpers.py
+++ b/esphome/helpers.py
@@ -9,6 +9,8 @@ import re
 import tempfile
 from urllib.parse import urlparse
 
+from esphome.const import __version__ as ESPHOME_VERSION
+
 _LOGGER = logging.getLogger(__name__)
 
 IS_MACOS = platform.system() == "Darwin"
@@ -503,3 +505,20 @@ _DISALLOWED_CHARS = re.compile(r"[^a-zA-Z0-9-_]")
 def sanitize(value):
     """Same behaviour as `helpers.cpp` method `str_sanitize`."""
     return _DISALLOWED_CHARS.sub("_", value)
+
+
+def docs_url(path: str) -> str:
+    """Return the URL to the documentation for a given path."""
+    # Local import to avoid circular import
+    from esphome.config_validation import Version
+
+    version = Version.parse(ESPHOME_VERSION)
+    if version.is_beta:
+        docs_format = "https://beta.esphome.io/{path}"
+    elif version.is_dev:
+        docs_format = "https://next.esphome.io/{path}"
+    else:
+        docs_format = "https://esphome.io/{path}"
+
+    path = path.removeprefix("/")
+    return docs_format.format(path=path)