Merge branch 'current' into current

Author: jesserockz

.devcontainer/devcontainer.json

@@ -1,7 +1,6 @@
-// https://github.com/microsoft/vscode-dev-containers/tree/v0.183.0/containers/python-3
 {
   "name": "ESPHome - docs",
-  "image": "mcr.microsoft.com/vscode/devcontainers/python:0-3.11",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
   "postCreateCommand": ".devcontainer/postCreate.sh",
   "postAttachCommand": "make live-html",
   "forwardPorts": [8000],
@@ -10,10 +9,6 @@
   },
   "customizations": {
     "vscode": {
-      "settings": {
-        "python.pythonPath": "/usr/local/bin/python"
-      },
-
       "extensions": ["ms-python.python"]
     }
   }

.github/workflows/check-labels.yml

@@ -0,0 +1,40 @@
+name: Check labels
+
+on:
+  pull_request_target:
+    types: [labeled, unlabeled]
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check labels
+        uses: actions/github-script@v7.0.1
+        with:
+          script: |
+            const { data: labels } = await github.rest.issues.listLabelsOnIssue({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+            const hasParent = labels.find(label => label.name === "has-parent");
+            const current = labels.find(label => label.name === "current");
+            if (hasParent && current) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: ["wrong-base-branch"]
+              });
+
+              await github.rest.pulls.createReview({
+                pull_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                event: "REQUEST_CHANGES",
+                body: "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."
+              });
+
+              core.setFailed("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.");
+            }

Dockerfile

@@ -4,7 +4,6 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         curl \
         git \
         make \
-        doxygen \
         openssh-client \
         software-properties-common \
         && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*

Doxygen

@@ -38,7 +38,7 @@ PROJECT_NAME           = "ESPHome"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2025.3.3
+PROJECT_NUMBER         = 2025.5.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

Makefile

@@ -1,10 +1,10 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2025.3.3
+ESPHOME_REF = 2025.5.1
 PAGEFIND_VERSION=1.1.1
 PAGEFIND=pagefind
 NET_PAGEFIND=../pagefindbin/pagefind
 
-.PHONY: pagefind build-html html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify
+.PHONY: pagefind build-html html html-strict cleanhtml deploy help live-html live-pagefind Makefile netlify netlify-dependencies svg2png copy-svg2png minify
 
 html: pagefind
 	sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
@@ -33,33 +33,13 @@ svg2png:
 help:
 	sphinx-build -M help . _build $(O)
 
-api:
-	mkdir -p _build/html/api
-	@if [ ! -d "$(ESPHOME_PATH)" ]; then \
-	  git clone --branch $(ESPHOME_REF) https://github.com/esphome/esphome.git $(ESPHOME_PATH) || \
-	  git clone --branch beta https://github.com/esphome/esphome.git $(ESPHOME_PATH); \
-	fi
-	ESPHOME_PATH=$(ESPHOME_PATH) doxygen Doxygen
-
 net-html:
+	sed -i 's@{{API_DOCS_URL}}@'"${API_DOCS_URL}"'@' _redirects
 	sphinx-build -M html . _build -j auto -n $(O)
 	mkdir -p _pagefind/pagefind
 	${NET_PAGEFIND}
 	sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
 
-netlify-api: netlify-dependencies
-	mkdir -p _build/html/api
-	@if [ ! -d "$(ESPHOME_PATH)" ]; then \
-	  git clone --branch $(ESPHOME_REF) https://github.com/esphome/esphome.git $(ESPHOME_PATH) || \
-	  git clone --branch beta https://github.com/esphome/esphome.git $(ESPHOME_PATH); \
-	fi
-	ESPHOME_PATH=$(ESPHOME_PATH) ../doxybin/doxygen Doxygen
-
-netlify-dependencies: pagefind-binary
-	mkdir -p ../doxybin
-	curl -L https://github.com/esphome/esphome-docs/releases/download/v1.10.1/doxygen-1.8.13.xz | xz -d >../doxybin/doxygen
-	chmod +x ../doxybin/doxygen
-
 pagefind-binary:
 	mkdir -p ../pagefindbin
 	curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$(PAGEFIND_VERSION)/pagefind-v$(PAGEFIND_VERSION)-x86_64-unknown-linux-musl.tar.gz -L
@@ -71,7 +51,7 @@ pagefind-binary:
 copy-svg2png:
 	cp svg2png/*.png _build/html/_images/
 
-netlify: netlify-dependencies netlify-api net-html copy-svg2png
+netlify: pagefind-binary net-html copy-svg2png
 
 lint: html-strict
 	python3 lint.py

README.md

@@ -1,6 +1,11 @@
 # ESPHome-Docs [![Netlify Status](https://api.netlify.com/api/v1/badges/97a2e9ce-cee7-4cc8-8dc7-537c92a23fa7/deploy-status)](https://app.netlify.com/sites/esphome/deploys) [![Discord Chat](https://img.shields.io/discord/429907082951524364.svg)](https://discord.gg/KhAMKrd) [![GitHub release](https://img.shields.io/github/release/esphome/esphome.svg)](https://github.com/esphome/esphome/releases/)
 
-[![ESPHome-Docs Logo](https://esphome.io/_images/logo-docs.png)](https://esphome.io/)
+<a href="https://esphome.io/">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://esphome.io/_images/logo-docs-on-dark.svg", alt="ESPHome Logo">
+    <img src="https://esphome.io/_images/logo-docs.svg" alt="ESPHome Logo">
+  </picture>
+</a>
 
 **Documentation:** https://esphome.io/
 

_extensions/apiref.py

@@ -1,7 +1,8 @@
+import os
 import re
 import string
-from docutils import nodes, utils
 
+from docutils import nodes, utils
 
 value_re = re.compile(r"^(.*)\s*<(.*)>$")
 DOXYGEN_LOOKUP = {}
@@ -13,6 +14,8 @@
 DOXYGEN_LOOKUP["_"] = "__"
 DOXYGEN_LOOKUP["."] = "_8"
 
+API_DOCS_URL = os.getenv("API_DOCS_URL", "https://api-docs.esphome.io")
+
 
 def split_text_value(value):
     match = value_re.match(value)
@@ -25,38 +28,42 @@ def encode_doxygen(value):
     value = value.split("/")[-1]
     try:
         return "".join(DOXYGEN_LOOKUP[s] for s in value)
-    except KeyError:
-        raise ValueError("Unknown character in doxygen string! '{}'".format(value))
+    except KeyError as exc:
+        raise ValueError(
+            "Unknown character in doxygen string! '{}'".format(value)
+        ) from exc
 
 
 def apiref_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     text, value = split_text_value(text)
     if text is None:
         text = "API Reference"
-    ref = "/api/{}.html".format(encode_doxygen(value))
+    ref = f"{API_DOCS_URL}/{encode_doxygen(value)}.html"
     return [make_link_node(rawtext, text, ref, options)], []
 
 
 def apiclass_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     text, value = split_text_value(text)
     if text is None:
         text = value
-    ref = "/api/classesphome_1_1{}.html".format(encode_doxygen(value))
+    ref = f"{API_DOCS_URL}/classesphome_1_1{encode_doxygen(value)}.html"
     return [make_link_node(rawtext, text, ref, options)], []
 
 
 def apistruct_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     text, value = split_text_value(text)
     if text is None:
         text = value
-    ref = "/api/structesphome_1_1{}.html".format(encode_doxygen(value))
+    ref = f"{API_DOCS_URL}/structesphome_1_1{encode_doxygen(value)}.html"
     return [make_link_node(rawtext, text, ref, options)], []
 
+
 def make_link_node(rawtext, text, ref, options=None):
     options = options or {}
     node = nodes.reference(rawtext, utils.unescape(text), refuri=ref, **options)
     return node
 
+
 def setup(app):
     app.add_role("apiref", apiref_role)
     app.add_role("apiclass", apiclass_role)

_redirects

@@ -1,5 +1,9 @@
 /esphomeyaml/* /:splat 301
 
+# This redirect is for the api docs that have been moved.
+# It is replaced by sed in the makefile when netlify is building the site.
+/api/* {{API_DOCS_URL}}/:splat 301
+
 # Moved components
 # e.g: /components/sensors/abc.html /components/sensors/xyz.html 301
 /components/sensor/sgp40.html /components/sensor/sgp4x.html 301
@@ -14,19 +18,21 @@
 /components/sensor/mmc5063.html /components/sensor/mmc5603.html 301
 /components/sensor/kalman_combinator.html /components/sensor/combination.html 301
 
-/components/binary_sensor/custom* /guides/contributing#a-note-about-custom-components 301
-/components/climate/custom* /guides/contributing#a-note-about-custom-components 301
-/components/cover/custom* /guides/contributing#a-note-about-custom-components 301
-/components/light/custom* /guides/contributing#a-note-about-custom-components 301
-/components/output/custom* /guides/contributing#a-note-about-custom-components 301
-/components/sensor/custom* /guides/contributing#a-note-about-custom-components 301
-/components/switch/custom* /guides/contributing#a-note-about-custom-components 301
-/components/text_sensor/custom* /guides/contributing#a-note-about-custom-components 301
-/custom/custom_component* /guides/contributing#a-note-about-custom-components 301
-/custom/i2c* /guides/contributing#a-note-about-custom-components 301
-/custom/index* /guides/contributing#a-note-about-custom-components 301
-/custom/spi* /guides/contributing#a-note-about-custom-components 301
-/custom/uart* /guides/contributing#a-note-about-custom-components 301
+/guides/contributing* https://developers.esphome.io/contributing/code/ 301
+
+/components/binary_sensor/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/climate/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/cover/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/light/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/output/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/sensor/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/switch/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/components/text_sensor/custom* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/custom/custom_component* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/custom/i2c* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/custom/index* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/custom/spi* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
+/custom/uart* https://developers.esphome.io/blog/2025/02/19/about-the-removal-of-support-for-custom-components/ 301
 
 /cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301
 /cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301