Use Doxygen tagfile for apiref shortcode

.gitignore

@@ -6,6 +6,7 @@ esphome-docs
 /pagefind/
 /data/repo.yaml
 /data/anchors.json
+/data/apirefs
 /data/automations
 my-secrets
 resources/_gen

Makefile

@@ -34,6 +34,10 @@ repo-data: directories
 	curl -s -S https://data.esphome.io/release/automations.json | script/collate_automations.sh > data/automations/current.json
 	curl -s -S https://data.esphome.io/beta/automations.json | script/collate_automations.sh > data/automations/beta.json
 	curl -s -S https://data.esphome.io/dev/automations.json | script/collate_automations.sh > data/automations/next.json
+	mkdir -p data/apirefs
+	curl -s -S https://api-docs.esphome.io/tags.xml | script/format_api_tags.py > data/apirefs/current.json
+	curl -s -S https://api-docs-beta.esphome.io/tags.xml | script/format_api_tags.py > data/apirefs/beta.json
+	curl -s -S https://api-docs-dev.esphome.io/tags.xml | script/format_api_tags.py > data/apirefs/next.json
 
 live-html:	anchors
 	$(PAGEFIND)
@@ -42,6 +46,7 @@ live-html:	anchors
 clean:
 	rm -rf public/*
 	rm -rf pagefind/*
+	rm -rf data/apiref/
 	rm -rf data/automations/
 	rm -rf data/repo.yaml
 	rm -rf resources/_gen

script/format_api_tags.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+# Takes GENERATE_TAGFILE from Doxygen and outputs a map
+# of file paths and class names to Doxygen URL
+
+import json, re, sys
+import xml.etree.ElementTree as ET
+
+tree = ET.parse(sys.stdin)
+root = tree.getroot()
+
+tags = {}
+
+for tag in root:
+    kind = tag.attrib["kind"]
+
+    # Skip pages and groups
+    if kind in ["group", "page"]:
+        continue
+
+    url = tag.find("filename").text
+    name = tag.find("name").text
+
+    # Prepend path to "file" tags
+    if kind == "file":
+        name = tag.find("path").text + name
+
+    # name = re.sub(r"^esphome(::|/(core|components)/)", "", name)
+
+    tags[name] = url
+
+    # Allow matches without "esphome::" or "esphome/" prefix
+    name = re.sub(r"^esphome(::|/)", "", name)
+    tags[name] = url
+
+    # Allow matches without "core/" or "components/" prefix
+    name = re.sub(r"^(core|components)/", "", name)
+    tags[name] = url
+
+print(json.dumps(tags))

themes/esphome-theme/layouts/shortcodes/apiref.html

@@ -21,19 +21,24 @@
     :apiref:`DisplayName <path/to/api/element>`
     :apiref:`esphome::sensor::Sensor` (uses path as display name)
 */ -}}
+{{- $branch := getenv "BRANCH" | default site.Params.branch | default "current" -}}
+{{- if eq $branch "new" -}}
+    {{- $branch = "current" -}}
+{{- end -}}
+{{- if not (in (slice "current" "beta" "next") $branch) -}}
+    {{- $branch = "next" -}}
+{{- end -}}
+{{- $data := index site.Data.apirefs $branch -}}
 {{- $text := .Get 0 -}}
 {{- $path := .Get 1 -}}
 {{- if eq $text $path -}}
     {{- $text = "API Reference" }}
 {{- end }}
-{{- $lastPathElement := index (last 1 (split $path "/")) 0 -}}
-{{- $processedPath := replace (replace (replace $lastPathElement "_" "__") "." "_8") ":" "_1" -}}
-{{ $match := findRE `([A-Z])` $processedPath }}
-{{ range $match }}
-{{ $original := . }}
-{{ $lower := lower . | printf "_%s" }}
-{{ $processedPath = replace $processedPath $original $lower }}
-{{ end }}
+{{ $processedPath := index $data $path }}
+
+{{- if not (isset $data $path) -}}
+{{- warnf "Could not find API reference for '%s' in %s" $path $.Page.File.Path -}}
+{{- end -}}
 
 {{- $baseUrl := .Site.Params.api_docs_url -}}
 <a href="{{ $baseUrl }}/{{ $processedPath }}">{{ $text }}</a>