Zum Inhalt

Website, Diagramme und Screenshots

Die Website der Dokumentation, und die Diagramme und Screenshots, die sich selbst aktuell halten.

Website

Die Dokumentation aus docs/ als Website mit Suche und hellem und dunklem Design, das dem System folgt, bis der Leser eines wählt, auf Englisch und, mit deutschen Seiten wie index.de.md neben den englischen, auf Deutsch: jeder Pull Request baut sie streng und prüft die gebauten Seiten: jeden Link und jeden Anker, auch die in HTML geschriebenen, mit lychee und ohne Netz, und was die Hooks der Website versprechen, etwa eine Sitemap in jedem Ordner mit Seiten und die 404-Seite in der Standardsprache, dass keine Seite mehr als 1.200 KB auf einmal lädt und dass jede Seite jedes Bild ihres Markdowns zeigt, die Teile der README eingeschlossen, mit blueprint.py site-check, und scripts/check-site.sh ergänzt die Prüfungen des Projekts; ebenso scripts/check.sh, sobald die Werkzeuge ihrer Vorschau installiert sind, unter Linux, macOS und Windows; jede Änderung an main veröffentlicht den Build dieses Checks auf GitHub Pages, mit dem, was ein Hook in site/.well-known/ schreibt, und die Schriften und Skripte, die er herunterlädt, bleiben eine Woche im Cache, signiert seine Herkunft, die gh attestation verify prüft, und fragt die veröffentlichte Website nach der Startseite jeder Sprache; barrierefrei, mit dem Kontrast und den unterstrichenen Links, die WCAG 2.2 AA verlangt, was axe-core in jedem Pull Request auf jeder Seite in beiden Designs prüft; schnell auf dem Handy, mit Bildern, die erst laden, wenn der Leser zu ihnen kommt, einem GIF mit einem MP4 daneben als dieses Video, einem Bild für jedes Design, das nur in seinem Design lädt, einem Bild, das die README von main ihres eigenen Repositorys zeigt, etwa https://github.com/OWNER/NAME/raw/main/screenshots/settings.png, aus dem Checkout, sodass der Pull Request, der einen Screenshot hinzufügt, ihn auch auf seiner Website zeigt, und einem, das Git nicht verfolgt, das den Build scheitern lässt, den Diagrammen als ihre Bilder statt als Mermaid und einer festen Version von Mermaid für einen verbliebenen mermaid-Block; in der Sprache jeder Seite für die Suche und Suchmaschinen, mit einer Beschreibung und dem Datum ihrer neuesten Datei für jede Seite, den vollen Adressen ihrer Sprachen und ohne eine Seite ohne Übersetzung in Suchmaschinen; die Badges bleiben auf GitHub; ein Header, der die Version des neuesten Releases zeigt, die die Hooks beim Build aus Git lesen, sodass keine Seite den Browser des Lesers die API von GitHub fragen lässt, was blueprint.py site-check prüft, und ein Footer mit Links zum Owner auf GitHub, zu seiner Website mit all seinen Projekten und zu GitHub Sponsors, wie .github/FUNDING.yml es nennt, in der Sprache der Seite, sofern mkdocs.yml nicht extra.social setzt; eine Seite Automatisierung, die die Hooks bei jedem Build aus .github/workflows/ schreiben, auf Englisch und Deutsch: jeder Workflow mit dem Kommentar an seinem Anfang und dem, was ihn startet, jeder Zeitplan in Worten, die Prüfungen, die main verlangt, und die Umgebungen und Secrets, die er nutzt, und an ihrer Stelle eine docs/automation.md des Projekts.

Womit: MkDocs mit dem Material-Theme, mkdocs.yml, docs.yml, .github/mkdocs_blueprint.py, .github/a11y/.

Diagramme, die sich selbst reparieren

Jedes Diagramm als Bild, das alle sehen, auch in der GitHub-App, in den Stores und in E-Mails, die kein Mermaid zeichnen: eine Mermaid-Quelle in docs/diagrams/, gezeichnet als SVG für das helle und eines für das dunkle Design, die auch die Website zeigt, im Design, zu dem die Lesenden wechseln, sodass eine Seite mit Diagramm kein Mermaid lädt; die Prüfung diagrams zeichnet die Bilder in jedem Pull Request neu, der ein Diagramm ändert oder einen mermaid-Block hinzufügt, und der Diagramm-Bot committet Quellen und Bilder auf seinen Branch; auf main behebt ein Pull Request des Diagramm-Bots, was noch fehlt, und merged sich selbst; bash scripts/diagrams.sh --extract macht aus den mermaid-Blöcken vorhandenen Markdowns Quellen und ihre Bilder.

Womit: scripts/diagrams.sh mit mermaid-cli, lint.yml, after-checks.yml, diagrams.yml.

Die GitHub-App, HACS, der Nextcloud App Store, PyPI und die E-Mails von GitHub zeichnen kein Mermaid und zeigen einen mermaid-Block als Code. Darum ist jedes Diagramm ein Bild seiner Quelle, und die Bots halten das ohne einen Menschen so.

Wie sich die Diagramme selbst reparieren: Ein Pull Request, der einen mermaid-Block hinzufügt oder ein Diagramm ändert, und Renovate mit einer neuen Version von mermaid-cli führen die Prüfung diagrams aus, die die Diagramme neu zeichnet. Auf einem Branch des Repositorys committet der Diagramm-Bot die Quellen und Bilder auf den Branch, und die Prüfungen laufen erneut; ein Fork behält die fehlschlagende Prüfung, die den Befehl nennt. Nach dem Merge und jede Woche wird auch main gezeichnet: Ist ein Diagramm noch kein Bild seiner Quelle, behebt das ein Pull Request von bot/diagrams, der sich selbst merged. So sehen alle Leser jedes Diagramm.Wie sich die Diagramme selbst reparieren: Ein Pull Request, der einen mermaid-Block hinzufügt oder ein Diagramm ändert, und Renovate mit einer neuen Version von mermaid-cli führen die Prüfung diagrams aus, die die Diagramme neu zeichnet. Auf einem Branch des Repositorys committet der Diagramm-Bot die Quellen und Bilder auf den Branch, und die Prüfungen laufen erneut; ein Fork behält die fehlschlagende Prüfung, die den Befehl nennt. Nach dem Merge und jede Woche wird auch main gezeichnet: Ist ein Diagramm noch kein Bild seiner Quelle, behebt das ein Pull Request von bot/diagrams, der sich selbst merged. So sehen alle Leser jedes Diagramm.

  • Ein Pull Request repariert sich selbst: Fügt ein Pull Request von einem Branch des Repositorys einen mermaid-Block hinzu oder ändert er eine Quelle, führt die Prüfung diagrams bash scripts/diagrams.sh --extract aus, und der Diagramm-Bot committet die Quellen und Bilder, die dabei entstehen, als Release-App auf den Branch, mit einem Kommentar, der die geänderten Seiten nennt. Die Prüfungen dieses Commits bestehen. Ein Pull Request aus einem Fork bekommt die fehlschlagende Prüfung, deren Zusammenfassung die Dateien und den Befehl nennt.
  • main repariert sich selbst: Nach jeder Änderung von main, die ein Diagramm betrifft oder einen mermaid-Block hinzufügt, und jede Woche zeichnet der Workflow Diagrams alle Diagramme von main. Fehlt etwas, etwa die Blöcke eines Repositorys direkt nach dem Update des Blueprints, hält er einen Pull Request vom Branch bot/diagrams mit der Korrektur, der sich selbst merged, sobald alle Prüfungen bestehen, und schließt ihn, wenn main anders repariert wurde. Ein fehlgeschlagener Lauf öffnet ein Issue, das der wöchentliche Lauf schließt, sobald der Bot wieder besteht.
  • Ein neuer Renderer zeichnet neu: Renovate hält das Image von mermaid-cli in scripts/diagrams.sh aktuell; die Prüfung zeichnet die Bilder auf seinem Branch neu, und der Diagramm-Bot committet sie, sodass das Update weiterhin von selbst merged.
  • Nur Diagramme: Der Bot führt keinen Code eines Pull Requests aus. Er committet nur Quellen in docs/diagrams/, SVG-Bilder in docs/images/diagrams/ und Markdown-Seiten, mit einfachen Pfaden, auf genau den Commit, den die Prüfung gezeichnet hat, und nur für einen Branch des Repositorys.

Screenshots, die sich selbst erneuern

Die Bilder des Projekts, die ein Bot nur erneuert, wenn sich ihre Pixel ändern: nach einer Änderung dessen, was sie zeigen, nach jedem Release und jede Woche führt der Screenshot-Bot scripts/screenshots.sh ohne Secrets aus und hält einen Pull Request mit den Bildern, die anders aussehen, der sich selbst merged; ein neues Repository beginnt mit einem Skript, das die Social Preview rendert und seine Website und, nach seiner Art, seine Integration in Home Assistant oder seine App in Nextcloud fotografiert, jedes in Docker und in beiden Themes.

Womit: scripts/screenshots.sh, .github/screenshots-paths.txt, screenshot-bot.yml.

Die Bilder eines Projekts, in seiner README, auf seiner Website und in den Stores, zeigen es so, wie es war, als jemand sie zuletzt aufgenommen hat. Der Screenshot-Bot nimmt sie neu auf, sobald sich ändern kann, was sie zeigen, und ändert eine Datei nur, wenn sich ihre Pixel ändern.

Wie sich die Screenshots selbst erneuern: Nach einer Änderung von main, die eine Datei aus .github/screenshots-paths.txt betrifft, nach jedem Release, jede Woche und auf Wunsch sucht der Screenshot-Bot scripts/screenshots.sh; ohne das Skript rendert er nichts. Das Skript rendert die Bilder ohne Secrets, und jedes Bild, dessen Pixel gleich blieben, behält seine committete Datei. Haben sich Pixel geändert, hält ein Pull Request von bot/screenshots die neuen Bilder und merged sich selbst, sobald alle Prüfungen bestehen; sieht main aus wie gerendert, schließt der Bot ihn. So zeigt jedes Bild das Projekt, wie es ist.Wie sich die Screenshots selbst erneuern: Nach einer Änderung von main, die eine Datei aus .github/screenshots-paths.txt betrifft, nach jedem Release, jede Woche und auf Wunsch sucht der Screenshot-Bot scripts/screenshots.sh; ohne das Skript rendert er nichts. Das Skript rendert die Bilder ohne Secrets, und jedes Bild, dessen Pixel gleich blieben, behält seine committete Datei. Haben sich Pixel geändert, hält ein Pull Request von bot/screenshots die neuen Bilder und merged sich selbst, sobald alle Prüfungen bestehen; sieht main aus wie gerendert, schließt der Bot ihn. So zeigt jedes Bild das Projekt, wie es ist.

  • Ein Skript schaltet ihn ein: Jedes Repository hat den Workflow Screenshots (screenshot-bot.yml), der nichts rendert, solange das Projekt kein scripts/screenshots.sh hat. Das Skript rendert die Bilder an Ort und Stelle, wo auch immer die Dokumentation, die Stores oder die Social Preview sie hernehmen; ein neues Repository beginnt mit einem, das die Social Preview .github/social-preview.png rendert und fotografiert, was es macht, wie der nächste Punkt sagt. .github/screenshots-paths.txt listet die Dateien, deren Änderung die Bilder ändern kann, wie die Pfade eines Workflows. Beide gehören dem Projekt, ein Update des Blueprints lässt sie also in Ruhe.
  • Was ein neues Repository fotografiert: die Startseite seiner Website, die das Skript mit den Werkzeugen in .venv-docs baut; eine Home-Assistant-Integration auch ihre Seite in einem Home Assistant in Docker, der mit custom_components/ läuft und die Integration über ihren Config Flow eingerichtet hat, und eine Nextcloud-App die App in den Apps der Einstellungen einer Nextcloud in Docker, mit eingeschalteter App. Jedes Bild kommt als docs/images/screenshots/<name>.png im hellen Theme und <name>.dark.png im dunklen, für ein <picture>, aufgenommen vom Chromium des Images der Social Preview mit Playwright, mit Hashes gepinnt in .github/screenshots-browser-requirements.txt, das Renovate zusammen mit dem Image bewegt. Server und Browser teilen ein Docker-Netz ohne Weg nach draußen, die Uhr des Browsers steht still, sein Fenster ist 1280×800 groß, und die Buchstaben haben graue Kanten, sodass derselbe Code dieselben Pixel rendert; Renovate hält die Images von Home Assistant und Nextcloud im Skript aktuell, und ein Projekt fügt seine eigenen Bilder der Funktion shoot() hinzu.
  • Wann er rendert: nach einer Änderung von main, die eine Datei der Liste, das Skript oder die Liste betrifft, nach jedem Release, dessen Version ein Bild zeigen kann, jeden Freitag und auf Wunsch. Er führt das Skript ohne Secrets aus, mit einem Token, das nur liest, mit Docker, mit der ganzen History, damit die Website das Datum jeder Seite wie veröffentlicht zeigt, und mit den Werkzeugen der Website in .venv-docs, wie CONTRIBUTING.md sie einrichtet, für ein Skript, das ihre Seiten fotografiert.
  • Nur Pixel zählen: blueprint.py screenshots keep vergleicht jedes Bild, das das Skript geändert hat, mit dem von main nach seinen Pixeln, bei einer Animation Frame für Frame, und gibt jedem, das gleich aussieht, seine committete Datei zurück, sodass ein neuer Encoder, Browser oder Runner keine Datei ändert. Ein Frame, der den vorigen wiederholt, zählt einmal, die Zeit, die jeder Frame zeigt, gar nicht, und ein ganz durchsichtiges Pixel hat keine Farbe.
  • Ein Pull Request, der sich selbst merged: Haben sich Pixel geändert, hält der Bot einen Pull Request von bot/screenshots, docs: update the screenshots, als Release-App, mit einer Tabelle der Bilder und dem Anteil der geänderten Pixel in jedem. Er merged sich selbst, sobald alle Prüfungen bestehen, der Bot hält ihn mit main aktuell und schließt ihn, wenn main ohne ihn aussieht wie gerendert. Eine geänderte Social Preview bekommt die Erinnerung, sie unter Settings → General → Social preview hochzuladen. Ohne die Release-App warnt der Lauf und hebt die Bilder drei Tage als Artefakt auf.
  • Nichts als Bilder: Der Job mit der Release-App führt nichts vom Skript aus. Er nimmt PNG-, JPEG-, GIF- und WebP-Dateien, deren Inhalt so beginnt wie ihre Art, mit einfachen Pfaden, außerhalb von .git und der Workflows, und lässt jede andere Datei weg, die das Skript geändert hat, was die Beschreibung des Pull Requests nennt. Viele Bilder gehen in mehreren Commits. Ein fehlgeschlagener Lauf hält ein Issue des Bot-Health-Bots offen, bis ein Lauf wieder besteht.
  • Auf deinem Rechner: bash scripts/screenshots.sh, dann python3 .github/blueprint.py screenshots restore, das jedem Bild, das gleich aussieht, seine committete Datei zurückgibt und die anderen auflistet. Es vergleicht die Pixel mit Pillow, das python3 -m pip install --require-hashes -r .github/screenshots-requirements.txt installiert.
  • Auch die Bilder des Blueprints erneuern sich selbst: Nach einem Release, das die Fragen, das Template, die Workflows oder das Dashboard geändert hat, wie .github/docs-pictures/paths.txt sie listet, und auf Wunsch führt der Workflow Docs pictures scripts/docs-pictures.sh aus, das copier copy aufnimmt und das Dashboard und, mit .github/docs-pictures/github_pages.py, Seiten von GitHub fotografiert, die sich nicht mehr ändern, wie sie ein Leser ohne Konto sieht: ein Update des Blueprints mit seinen Prüfungen, die Assets eines Releases und den Kommentar des PR-Coachs, in beiden Themes und mit einer Uhr lange nach ihnen, damit GitHub ihre Daten ausschreibt. Es hält auf dieselbe Weise einen Pull Request von bot/pictures, docs: renew the pictures.