feat(docs): auto-generated web-apps landing page + generalized app hosting - #728
Merged
Conversation
…sting - The docs workflow now hosts ANY component's web/ directory (components/*/web/*.html + .js) automatically instead of hardcoding the two existing dirs, and generates docs/apps/index.html afterward. - New doc/generate_apps_index.py builds the landing page from each app's <title> and <meta name=description> -- a future app is listed by simply having those two tags, no registry to maintain. Theme-aware (light/dark), responsive card grid. - Added <meta name=description> to all five existing apps (head-only edits). - New doc/en/web_apps.rst (linked from the docs index) describing the hosted tools and the add-an-app convention. Verified locally: the generator indexes all 5 apps with titles+descriptions and the output parses cleanly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Adds an auto-generated “Web Apps” landing page and generalizes docs hosting so any component web app is published and discoverable.
Changes:
- Added a Python generator that builds
docs/apps/index.htmlby extracting<title>and<meta name="description">from hosted app HTML files. - Updated docs publish workflow to copy
components/*/web/*.html(and same-origin.js) intodocs/apps/and run the generator. - Added a new docs page (
web_apps.rst) and linked it from the main docs index; addedmeta descriptiontags to existing apps.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
doc/generate_apps_index.py |
Generates docs/apps/index.html by scanning hosted app HTML and building a card grid. |
doc/en/web_apps.rst |
New documentation page describing hosted web tools and the “add an app” convention. |
doc/en/index.rst |
Links the new Web Apps docs page from the documentation index. |
components/usb_device/web/board_console.html |
Adds meta name="description" for landing-page indexing. |
components/odrive_ascii/web/odrive_webusb_console.html |
Adds meta name="description" for landing-page indexing. |
components/odrive_ascii/web/odrive_control_panel.html |
Adds meta name="description" for landing-page indexing. |
components/odrive_ascii/web/odrive_console.html |
Adds meta name="description" for landing-page indexing. |
components/odrive_ascii/web/hid_visualizer.html |
Adds meta name="description" for landing-page indexing. |
.github/workflows/build_and_publish_docs.yml |
Generalizes copying of web apps and runs the index generator during docs build. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| consoles=(../components/odrive_ascii/web/*.html) | ||
| if [ ${#consoles[@]} -gt 0 ]; then | ||
| cp "${consoles[@]}" ../docs/apps/ | ||
| apps=(../components/*/web/*.html ../components/*/web/*.js) |
Comment on lines
+16
to
+25
| from pathlib import Path | ||
|
|
||
|
|
||
| def extract(path: Path): | ||
| text = path.read_text(encoding="utf-8", errors="replace") | ||
| title_m = re.search(r"<title>(.*?)</title>", text, re.S | re.I) | ||
| desc_m = re.search( | ||
| r'<meta\s+name=["\']description["\']\s+content=["\'](.*?)["\']', text, re.S | re.I) | ||
| title = html.unescape(title_m.group(1).strip()) if title_m else path.stem | ||
| desc = html.unescape(desc_m.group(1).strip()) if desc_m else "" |
Comment on lines
+29
to
+30
| def main() -> int: | ||
| apps_dir = Path(sys.argv[1]) |
Comment on lines
+39
to
+42
| cards.append( | ||
| f' <a class="card" href="{html.escape(app.name)}">\n' | ||
| f" <h2>{html.escape(title)}</h2>\n" | ||
| f" <p>{html.escape(desc) if desc else ' '}</p>\n" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Makes the hosted browser tools findable and future-proof:
docs/apps/index.htmllanding page, auto-generated at docs-build time from each app's<title>+<meta name="description">— a new app is listed by simply having those two tags. Theme-aware (light/dark) responsive card grid linking every app.components/*/web/*.html(+ same-origin.js) intodocs/apps/instead of hardcoding the two existing directories — dropping an app into a component'sweb/dir is all it takes.<meta name="description">added to all five existing apps (Board Console & Flasher, ODrive Web Serial / WebUSB consoles, ODrive Native control panel, WebHID visualizer). Head-only edits, so they won't conflict with the in-flight web fixes on feat(usb_device): ODrive-compatible USB device example (ASCII + native/Fibre + HID) #725.doc/en/web_apps.rst, linked from the docs index) describing the tools and the add-an-app convention.Once merged, the landing page lives at
esp-cpp.github.io/espp/apps/.Testing
🤖 Generated with Claude Code