Build the docs even when ESP build fails

.github/workflows/docs.yaml

@@ -27,6 +27,7 @@ jobs:
             - name: Checkout
               uses: actions/checkout@v4
             - name: Build ESP binaries
+              continue-on-error: true
               uses: ./.github/actions/build-esp
             - name: Setup Pages
               uses: actions/configure-pages@v4
@@ -50,7 +51,6 @@ jobs:
             name: github-pages
             url: ${{ steps.deployment.outputs.page_url }}
         runs-on: ubuntu-latest
-        # TODO improve this so that if esp build fails, publish the docs anyway (with a warning in the installer page)
         needs: build_and_upload
         steps:
             - name: Deploy to GitHub Pages

.pre-commit-config.yaml

@@ -17,6 +17,7 @@ repos:
                 - python
                 - image
                 - shell
+                - plain-text
             entry: pnpm exec prettier --write
 
           - id: clang-format

README.md

@@ -1,6 +1,6 @@
 # Welcome to SunTransit
 
-An ESP32 project to monitor departures of the Berliner Verkehrsbetriebe (BVG) using Sunton development boards.
+An [ESP32](https://www.espressif.com/en/products/socs/esp32) project to monitor departures of the [Berliner Verkehrsbetriebe (BVG)](https://www.bvg.de) using Sunton development boards.
 
 <p align="center">
   <img src="docs/ui.png" width="500" alt="Sunton 3248S035C board (front), configuration panel (back)"/>

docs/development.md

@@ -1,7 +1,7 @@
 The project is composed of three main parts:
 
 -   The ESP32 project, developed with the [ESP-IDF framework](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/)
--   The native simulator for the GUI (based on [LVGL](https://lvgl.io/))
+-   The Linux simulator for the GUI (based on [LVGL](https://lvgl.io/))
 -   The frontend React SPA served by the ESP32 which allows to configure it and get system information
 
 ## Dependencies

docs/installer.md

@@ -1,6 +1,10 @@
 # Firmware Web Installer
 
-Click the button below to installer the latest development firmware onto your device.
+{% if config.extra['has_firmware'] %}
+Click the button below to installer the latest development firmware (commit [{{ git.short_commit }}]({{ config['repo_url'] }}/commit/{{ git.commit }})). Powered by [ESP Web Tools](https://esphome.github.io/esp-web-tools/).
 
 <!-- TODO The dialog styling does not match the rest, fix it -->
 <esp-web-install-button manifest="/installer/manifest.json"/>
+{% else %}
+Something went wrong when building the latest version of the firmware.
+{% endif %}

docs/related.md

@@ -1,12 +1,17 @@
 A non-exhaustive collection of projects with the same or a similar goal as SunTransit:
 
-| Link                                                                                        | Description                                                                                                           | Open source      |
-| :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- | ---------------- |
-| [bvg-grabber](https://github.com/MarkusH/bvg-grabber)                                       | Python script to show [BVG](https://www.bvg.de/) real-time departures on a screen connected to the Raspberry Pi       | :material-check: |
-| [bvg-monitor-berlin](https://github.com/RocketRene/bvg-monitor-berlin)                      | [BVG](https://www.bvg.de/) public transport departures on an ESP32 with 320x240 display                               | :material-check: |
-| [esp32_ssd1306_metaefa](https://github.com/aschuma/esp32_ssd1306_metaefa)                   | Real-time departures of the [VVS](https://www.vvs.de/) (Stuttgart public transport) on a Wemos Lolin32 OLED board     | :material-check: |
-| [home-assistant-berlin-transport](https://github.com/vas3k/home-assistant-berlin-transport) | [VBB](https://www.vbb.de/)/[BVG](https://www.bvg.de/) transport widget for Home Assistant (iOS)                       | :material-check: |
-| [MMM-PublicTransportBerlin](https://github.com/deg0nz/MMM-PublicTransportBerlin)            | [MagicMirror](https://github.com/MichMich/MagicMirror) module to show real-time [BVG](https://www.bvg.de/) departures | :material-check: |
-| [mvv-display-for-ESP32](https://github.com/florianlederer/mvv-display-for-ESP32)            | Real-time departures of the [MVV](https://www.mvv-muenchen.de/) (Munich public transport) on a ESP32 TTGO-T-Display   | :material-check: |
-| [vbbvg](https://github.com/deeplook/vbbvg)                                                  | CLI tool to display real-time departures for [VBB](https://www.vbb.de/)/[BVG](https://www.bvg.de/) public transport   | :material-check: |
-| [weilsiedichlieben.de](https://weilsiedichlieben.de/)                                       | Web-app showing real-time departures of the [BVG](https://www.bvg.de/), supports multiple stations                    | :material-close: |
+| Link                                                                                        | Description                                                                                              | Open source      |
+| :------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------- | ---------------- |
+| [bvg-grabber](https://github.com/MarkusH/bvg-grabber)                                       | Python script to show [BVG][bvg.de] real-time departures on a screen connected to the Raspberry Pi       | :material-check: |
+| [bvg-monitor-berlin](https://github.com/RocketRene/bvg-monitor-berlin)                      | [BVG][bvg.de] public transport departures on an ESP32 with 320x240 display                               | :material-check: |
+| [esp32_ssd1306_metaefa](https://github.com/aschuma/esp32_ssd1306_metaefa)                   | Real-time departures of the [VVS][vvs.de] (Stuttgart public transport) on a Wemos Lolin32 OLED board     | :material-check: |
+| [home-assistant-berlin-transport](https://github.com/vas3k/home-assistant-berlin-transport) | [VBB][vbb.de]/[BVG][bvg.de] transport widget for Home Assistant (iOS)                                    | :material-check: |
+| [MMM-PublicTransportBerlin](https://github.com/deg0nz/MMM-PublicTransportBerlin)            | [MagicMirror](https://github.com/MichMich/MagicMirror) module to show real-time [BVG][bvg.de] departures | :material-check: |
+| [mvv-display-for-ESP32](https://github.com/florianlederer/mvv-display-for-ESP32)            | Real-time departures of the [MVV][mvv] (Munich public transport) on a ESP32 TTGO-T-Display               | :material-check: |
+| [vbbvg](https://github.com/deeplook/vbbvg)                                                  | CLI tool to display real-time departures for [VBB][vbb.de]/[BVG][bvg.de] public transport                | :material-check: |
+| [weilsiedichlieben.de](https://weilsiedichlieben.de/)                                       | Web-app showing real-time departures of the [BVG][bvg.de], supports multiple stations                    | :material-close: |
+
+[bvg.de]: https://www.bvg.de
+[vbb.de]: https://www.vbb.de
+[vvs.de]: htts://www.vvs.de
+[mvv]: https://www.mvv-muenchen.de/

mkdocs.yml

@@ -1,7 +1,7 @@
 site_name: SunTransit
 site_dir: docs_build
 site_url: https://suntrans.it
-repo_url: https://github.com/joined/suntransit
+repo_url: https://github.com/joined/SunTransit
 nav:
     - Home: index.md
     - Usage: usage.md
@@ -26,6 +26,7 @@ extra_css:
     - css/extra.css
 watch:
     - mkdocs/
+    - README.md
 markdown_extensions:
     # Python Markdown
     - abbr
@@ -63,6 +64,7 @@ plugins:
     - glightbox
     - gen-files:
           scripts:
-              - mkdocs/gen_index.py
+              - mkdocs/gen_files/gen_index.py
+    - macros
 hooks:
-    - mkdocs/gen_manifest.py
+    - mkdocs/hooks/gen_manifest.py

mkdocs/gen_manifest.py → mkdocs/hooks/gen_manifest.py

@@ -2,17 +2,10 @@
 from pathlib import Path
 import shutil
 
-IN_FIRMWARE_PATH = Path(__file__).parent.parent / "build" / "merged-firmware.bin"
+IN_FIRMWARE_PATH = Path(__file__).parent.parent.parent / "build" / "merged-firmware.bin"
 
 
 def get_firmware_content():
-    if not IN_FIRMWARE_PATH.exists():
-        print(
-            f"Could not find firmware at {IN_FIRMWARE_PATH}, using dummy firmware"
-        )
-
-        return "{}"
-
     manifest = {
         "name": "SunTransit",
         # TODO Get version from somewhere, like Git (hash / hash-dirty)
@@ -35,6 +28,7 @@ def generate_espwebtools_manifest(site_dir: str):
     with open(MANIFEST_PATH, "w") as out_file:
         out_file.write(get_firmware_content())
 
+
 def copy_firmware(site_dir: str):
     if not IN_FIRMWARE_PATH.exists():
         return
@@ -44,6 +38,14 @@ def copy_firmware(site_dir: str):
     shutil.copyfile(IN_FIRMWARE_PATH, OUT_FIRMWARE_PATH)
 
 
+def on_config(config, **kwargs):
+    config.extra["has_firmware"] = IN_FIRMWARE_PATH.exists()
+    return config
+
+
 def on_post_build(config, **kwargs):
+    if not config.extra["has_firmware"]:
+        return
+
     generate_espwebtools_manifest(config["site_dir"])
     copy_firmware(config["site_dir"])

requirements.txt

@@ -3,3 +3,4 @@ mkdocs
 mkdocs-material
 mkdocs-glightbox
 mkdocs-gen-files
+mkdocs-macros-plugin