[core] Move docs url generator to helpers.py (#10056)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

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
 

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)