Merge branch 'current' into patch-1

.github/workflows/docker.yml

@@ -18,9 +18,17 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
+      -
+        name: Install pagefind
+        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        with:
+          repo: cloudcannon/pagefind
       -
         name: Checkout source code
-        uses: actions/checkout@v4.1.0
+        uses: actions/checkout@v4.1.6
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
       -
         name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -43,6 +51,7 @@ jobs:
         with:
           context: .
           push: true
+          platforms: linux/amd64,linux/arm64
           tags: |
             esphome/esphome-docs:latest
             ghcr.io/esphome/esphome-docs:latest

.github/workflows/lint.yml

@@ -19,7 +19,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4.1.0
+    - name: Install pagefind
+      uses: jaxxstorm/action-install-gh-release@v1.12.0
+      with:
+          repo: cloudcannon/pagefind
+    - uses: actions/checkout@v4.1.6
     - name: Set up Python 3.8
       uses: actions/setup-python@v5
       with:

.gitignore

@@ -11,3 +11,5 @@ venv
 .vscode
 *.DS_Store
 /.idea/
+
+_pagefind/

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.8-slim
+FROM python:3.12-slim
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
         curl \
@@ -9,10 +9,39 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         software-properties-common \
         && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*
 
-COPY requirements.txt .
+ENV PAGEFIND_VERSION="1.1.0"
+ARG TARGETARCH
+SHELL ["/bin/bash", "-c"]
+RUN <<EOF
+    export TARGETARCH=${TARGETARCH/arm64/aarch64}
+    export TARGETARCH=${TARGETARCH/amd64/x86_64}
+    curl -o pagefind.tar.gz https://github.com/CloudCannon/pagefind/releases/download/v$PAGEFIND_VERSION/pagefind-v$PAGEFIND_VERSION-$TARGETARCH-unknown-linux-musl.tar.gz -L
+    tar xzf pagefind.tar.gz
+    rm pagefind.tar.gz
+    mv pagefind /usr/bin
+    chmod +x /usr/bin/pagefind
+EOF
+
+RUN useradd -ms /bin/bash esphome
+
+
+USER esphome
+
+WORKDIR /workspaces/esphome-docs
+ENV PATH="${PATH}:/home/esphome/.local/bin"
+
+COPY requirements.txt ./
 RUN pip3 install --no-cache-dir --no-binary :all: -r requirements.txt
 
 EXPOSE 8000
-WORKDIR /data/esphomedocs
 
 CMD ["make", "live-html"]
+
+LABEL \
+        org.opencontainers.image.title="esphome-docs" \
+        org.opencontainers.image.description="An image to help with ESPHomes documentation development" \
+        org.opencontainers.image.vendor="ESPHome" \
+        org.opencontainers.image.licenses="CC BY-NC-SA 4.0" \
+        org.opencontainers.image.url="https://esphome.io" \
+        org.opencontainers.image.source="https://github.com/esphome/esphome-docs" \
+        org.opencontainers.image.documentation="https://github.com/esphome/esphome-docs/blob/current/README.md"

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         = 2023.12.9
+PROJECT_NUMBER         = 2024.5.4
 
 # 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,12 +1,21 @@
 ESPHOME_PATH = ../esphome
-ESPHOME_REF = 2023.12.9
+ESPHOME_REF = 2024.5.4
+PAGEFIND_VERSION=1.1.0
+PAGEFIND=pagefind
+NET_PAGEFIND=../pagefindbin/pagefind
 
-.PHONY: html html-strict cleanhtml deploy help live-html 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-api api netlify-dependencies svg2png copy-svg2png minify
 
-html:
+html: pagefind
+	sphinx-build -M html . _build -j auto -n $(O) -Dhtml_extra_path=_redirects,_pagefind
+
+pagefind:
 	sphinx-build -M html . _build -j auto -n $(O)
-live-html:
-	sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0
+	mkdir -p _pagefind/pagefind
+	${PAGEFIND}
+
+live-html:	pagefind
+	sphinx-autobuild . _build -j auto -n $(O) --host 0.0.0.0 -Dhtml_extra_path=_redirects,_pagefind
 
 html-strict:
 	sphinx-build -M html . _build -W -j auto -n $(O)
@@ -32,6 +41,12 @@ api:
 	fi
 	ESPHOME_PATH=$(ESPHOME_PATH) doxygen Doxygen
 
+net-html:
+	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 \
@@ -40,19 +55,31 @@ netlify-api: netlify-dependencies
 	fi
 	ESPHOME_PATH=$(ESPHOME_PATH) ../doxybin/doxygen Doxygen
 
-netlify-dependencies:
+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
+	tar xzf pagefind.tar.gz
+	rm pagefind.tar.gz
+	mv pagefind ${NET_PAGEFIND}
+
+
 copy-svg2png:
 	cp svg2png/*.png _build/html/_images/
 
-netlify: netlify-dependencies netlify-api html copy-svg2png
+netlify: netlify-dependencies netlify-api net-html copy-svg2png
 
 lint: html-strict
 	python3 lint.py
 
+clean:
+	rm -rf _pagefind/
+	sphinx-build -M clean . _build $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

_static/custom.css

@@ -1,3 +1,9 @@
+/* provide this to be queried in JS. Sadly can't be used in media-queries just yet*/
+
+:root {
+  --mobile-width-stop: 875;
+}
+
 .row-odd {
   background-color: #f3f6f6;
 }
@@ -240,9 +246,56 @@ a:hover code {
   background: none;
 }
 
+/* don't underline links that contain an image and nothing else */
+a:has(> img:only-child) {
+  border-bottom: none;
+}
+
 div.body p, div.body dd, div.body li, div.body blockquote {
   hyphens: none;
 }
+.pagefind-ui__form {
+    width: 100%;
+    max-width: 300px;
+    left: auto;
+    right: auto;
+    position: relative;
+}
+
+.pagefind-modular-list-excerpt, .pagefind-modular-list-title {
+    color: #111111 !important;
+}
+
+.search-results {
+    background-color: #f8f8f8;
+    box-shadow: 0 6px 10px rgb(0 0 0 / 0.2);
+    position: fixed;
+    z-index: 1500;
+    padding-right: 6px;
+    padding-left: 6px;
+    border-radius: 12px;
+    overflow: auto;
+    width: 0;
+    height: fit-content;
+    max-width: 650px;
+    transition: height, width 0.1s ease-in-out;
+    display: none;
+}
+
+@media screen and (max-width: 875px) {
+  /* hide search result thumbnails on mobile */
+  .pagefind-modular-list-thumb {
+    width: 0;
+  }
+  /* reduce height of search box */
+  .pagefind-modular-input-wrapper {
+    scale: 90%;
+  }
+  .logo {
+    scale: 60%;
+  }
+}
+
 
 /* dark theme */
 @media (prefers-color-scheme: dark) {
@@ -339,4 +392,25 @@ div.body p, div.body dd, div.body li, div.body blockquote {
     background-color: #8e8129;
   }
 
+  .search-results {
+    background-color: #313131;
+    box-shadow: 0 6px 10px rgb(0 0 0 / 0.8);
+  }
+  .pagefind-modular-list-excerpt, .pagefind-modular-list-title {
+      color: #eeeeee !important;
+  }
+
+  .pagefind-ui__form, .pagefind-modular-input, .search-results {
+    color: #ececec !important;
+  }
+
+  :root {
+    --pagefind-ui-primary: #eeeeee;
+    --pagefind-ui-text: #eeeeee;
+    --pagefind-ui-background: #152028;
+    --pagefind-ui-border: #152028;
+    --pagefind-ui-tag: #152028;
+  }
+
+
 }

_static/version

@@ -1 +1 @@
-2023.12.9
+2024.5.4

_templates/layout.html

@@ -5,6 +5,7 @@
 {% endblock %}
 
 {%- block extrahead %}
+  <link href="/pagefind/pagefind-modular-ui.css" rel="stylesheet">
   <link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}?hash={{ custom_css_hash }}" type="text/css" />
   <link rel="apple-touch-icon" sizes="180x180" href="/_static/apple-touch-icon.png">
   <link rel="shortcut icon" href="/_static/favicon.ico">
@@ -16,6 +17,7 @@
   <link rel="icon" type="image/png" sizes="16x16" href="/_static/favicon-16x16.png">
   <link rel="manifest" href="/_static/site.webmanifest">
   <link rel="mask-icon" href="/_static/safari-pinned-tab.svg" color="#646464">
+  <link rel="me" href="https://fosstodon.org/@esphome">
   <meta name="apple-mobile-web-app-title" content="ESPHome">
   <meta name="application-name" content="ESPHome">
   <meta name="msapplication-TileColor" content="#dfdfdf">
@@ -24,23 +26,25 @@
   <meta name="HandheldFriendly" content="True">
   <meta name="MobileOptimized" content="320">
   <meta property="og:site_name" content="ESPHome">
-  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
+  <meta name="viewport"
+        content="width=device-width, initial-scale=1, maximum-scale=3, interactive-widget=overlays-content">
 {% endblock %}
 
 {% block relbar_top %}
-  {% if parents|length > 0 %}
   <ul class="breadcrumbs">
+  {% if parents|length > 0 %}
     {%- for doc in parents %}
       <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> ➔</li>
     {%- endfor %}
       <li>{{title}}</li>
-  </ul>
+
   {% endif %}
+  </ul>
 {% endblock %}
 
 {% block footer %}
   <div id="upgrade-footer">
-    A new version has been release since you last visited this page: {{ release }} 🎉
+    A new version has been released since you last visited this page: {{ release }} 🎉
     <div class="footer-button-container">
       <div role="button" id="upgrade-footer-dismiss" class="footer-button">Dismiss</div>
       <a id="upgrade-footer-changelog" class="footer-button" href="/changelog/{{ version }}.0.html">View Changelog</a>

_templates/search.html

@@ -0,0 +1,36 @@
+<!-- docs/_templates/search.html -->
+{% extends "page.html" %}
+
+{%- block htmltitle -%}
+<title>{{ _("Search") }} - {{ docstitle }}</title>
+{%- endblock htmltitle -%}
+
+{% block content %}
+<h1>{{ _("Search") }}</h1>
+<div id="search"></div>
+{% endblock %}
+
+{% block scripts -%}
+{{ super() }}
+{%- endblock scripts %}
+
+{% block extra_styles -%}
+{{ super() }}
+  <style type="text/css">
+    #search form input[type="text"] {
+      box-sizing: border-box;
+      width: 100%;
+      line-height: 2em;
+      padding-inline: 0.6em;
+      font-size: 1.2rem;
+      border-radius: 0.05rem;
+      border: 2px solid var(--color-foreground-border);
+      border-bottom-color: 2px solid var(--color-foreground-secondary);
+      transition: border-color 20ms ease;
+    }
+    #search form input[type="text"]:focus {
+      border-color: var(--color-foreground-primary);
+    }
+  </style>
+{%- endblock extra_styles %}
+