Ein Dokumentationsbuch pflegen, dessen Codebeispiele wie echter Code getestet werden

## Jeden Codeblock im Buch als getesteten Code behandeln, nicht nur als Text Das Buch ist eine Sammlung praktischer Beispiele, die als Markdown-Dateien mit eingebetteten Codeblöcken geschrieben sind. Ein Testrahmen für Dokumentationstests durchläuft den Quellbaum, extrahiert jeden Codeblock, kompiliert ihn und führt ihn aus. Ein fehlerhaftes Beispiel lässt den Build daher genauso scheitern wie fehlerhafter Anwendungscode. ### Was das für jede Bearbeitung bedeutet Ein Beispiel, das sich nicht kompilieren lässt, ist keine Dokumentation. Fließtext darf frei umformuliert werden, aber jede Änderung innerhalb eines Codeblocks ist eine Änderung an getestetem Quellcode und muss durch den Testbefehl laufen, bevor sie vorgeschlagen wird. ### Gerendertes Buch und Testfläche synchron halten Dasselbe Markdown speist sowohl das gerenderte Buch als auch den Testrahmen, deshalb tragen Formatierungsentscheidungen Bedeutung. Anmerkungen an einem Codeblock entscheiden darüber, wie der Testrahmen ihn behandelt, und Zeilen, die vor den Lesern verborgen sind, werden trotzdem kompiliert. Entferne niemals eine Anmerkung oder eine verborgene Zeile, nur damit die gerenderte Seite aufgeräumter aussieht. ## Das Buch mit den dokumentierten Befehlen bauen, testen und lokal ansehen Führe jede Routineaufgabe über die dokumentierten Befehle aus, statt eigene Aufrufe zu erfinden, damit lokale Durchläufe mit der kontinuierlichen Integration übereinstimmen. ### Die Befehle, auf die es ankommt - Das Buch aus den Markdown-Quellen bauen. - Die vollständige Testsuite ausführen, also die Dokumentationstests plus den Rechtschreibdurchlauf. - Nur das Dokumentationstest-Ziel ausführen, wenn du einen Codeblock geändert hast und die schnelle Schleife willst. - Das Buch lokal mit automatischem Neuladen bereitstellen, während du am Fließtext arbeitest. - Bauen und Testen zusammen als Standard vor der Begutachtung. - Die Linkprüfung ausführen, die interne und externe Links anhand einer eingecheckten Konfigurationsdatei validiert. - Das Rechtschreibskript interaktiv ausführen und berechtigte neue Wörter in die Wörterbuchdatei des Repositorys eintragen, damit die Ergänzung zusammen mit der Änderung geprüft wird. ### Die Werkzeugkette festnageln Der Buchgenerator und die Linkprüfung werden über einen einzigen dokumentierten Installationsbefehl in exakt festgelegten Versionen installiert. Aktualisiere kein Werkzeug lokal, um einen Fehlschlag zu umgehen, denn ein Versionsdrift macht aus einem reproduzierbaren Fehlschlag einen, den nur du sehen kannst. ## Die zwei Ablageformen für Beispiele kennen und gemeinsame Bibliotheksversionen nicht anheben Beispiele werden auf eine von zwei Arten getestet, und zu wissen, welches Muster eine Datei verwendet, bestimmt, wo ihr Code und ihre Abhängigkeiten liegen. ### Muster eins: Inline-Blöcke, die an Ort und Stelle getestet werden Die Codeblöcke stehen direkt im Markdown unterhalb des Quellbaums. Ein Build-Skript durchläuft diesen Baum auf der Suche nach Markdown-Dateien und erzeugt pro Codeblock einen Test. Jede Abhängigkeit, die ein solches Beispiel braucht, muss bereits im Wurzelmanifest vorhanden sein. Blöcke nehmen Anmerkungen für die Sprachedition und für Verhalten wie Nur-Kompilieren, Erwarteter-Absturz und Überspringen entgegen; Gerüstcode, den Leser nicht brauchen, wird als Zeilen geschrieben, denen ein Rautezeichen und ein Leerzeichen vorangestellt sind, und diese Zeilen kompiliert der Testrahmen, während das gerenderte Buch sie verbirgt. Dies ist das Altmuster: Es wird funktionsfähig gehalten, aber nicht erweitert. ### Muster zwei: eigenständige Pakete, die in das Markdown eingebunden werden Der Code liegt in einem eigenen Paket unterhalb eines gemeinsamen Codeverzeichnisses und hat ein unabhängiges Manifest; das Markdown zieht ihn über eine Einbindungsanweisung herein, die per relativem Pfad auf die Quelldatei zeigt. Einbindungen mit Zeilenbereich lassen eine Seite nur einen Teil einer Datei zeigen, und genau so wird das Testgerüst aus dem gerenderten Beispiel herausgehalten. Der Pfad wird im Build-Skript vom Dokumentationstest-Rahmen ausgeschlossen, damit der Code nicht zweimal getestet wird. Dies ist das bevorzugte Muster für neue und migrierte Beispiele. ### Die Regel für Abhängigkeiten Ändere keine Abhängigkeitsversionen im Wurzelmanifest. Das Wurzelmanifest wird von jedem Inline-Beispiel gemeinsam genutzt, deshalb kann eine Anhebung, die einer einzelnen Seite genügen soll, unbemerkt Dutzende andere zerstören. Wenn ein Beispiel eine neuere Abhängigkeit braucht, migriere stattdessen dieses Beispiel in ein eigenständiges Paket mit eigenen festgelegten Versionen. ## Ein Beispiel, das eine neuere Bibliothek braucht, in ein eigenes Paket verschieben Wenn sich eine Abhängigkeitsversion ändern muss, wandle die betroffenen Beispiele in eigenständige Pakete um. Führe die Schritte der Reihe nach aus, denn jeder Schritt hinterlässt das Repository in einem Zustand, auf den der nächste Schritt angewiesen ist. 1. Lege das Paket unterhalb des gemeinsamen Codeverzeichnisses an, in einem Ordner, der nach seiner Kategorie und dann nach dem Beispiel benannt ist, mit einem eigenen Manifest. Erbe gemeinsame Abhängigkeiten nach Möglichkeit vom Arbeitsbereich, oder lege Versionen unabhängig fest, wo gerade das Abweichen der ganze Zweck ist. 2. Verschiebe den Code aus dem Markdown-Codeblock in den Quellcode des Pakets: eine ausführbare Datei pro lauffähigem Beispiel oder ein Bibliotheksmodul für Beispiele im Bibliotheksstil. 3. Trage das Paket in die Mitgliederliste des Arbeitsbereichs im Wurzelmanifest ein. 4. Ersetze den Inline-Code im Markdown durch eine Einbindungsanweisung, deren relativer Pfad vom Ort der Markdown-Datei selbst zum Quellcode des Pakets führt. 5. Schließe den migrierten Pfad im Build-Skript vom Dokumentationstest-Rahmen aus. Es gibt zwei Ausschlusslisten: eine, die ein Verzeichnispräfix entgegennimmt und alles darunter entfernt, und eine, die eine einzelne Markdown-Datei entgegennimmt. Verwende die engere der beiden, die passt. 6. Teste beide Seiten: Führe die eigenen Tests des neuen Pakets aus und lasse das Dokumentationstest-Ziel erneut laufen, um zu bestätigen, dass das Entfernen des Blocks die verbliebenen Inline-Beispiele nicht beschädigt hat. Eine Migration, die vor Schritt fünf abbricht, lässt das Beispiel zweimal kompiliert zurück, und eine, die vor Schritt sechs abbricht, kann unbemerkt Testabdeckung verlieren. ## Die Dateien lesen, die festlegen, was gebaut und getestet wird Eine Handvoll Dateien entscheidet darüber, was getestet wird, was gerendert wird und welche Befehle es gibt. Lies sie, bevor du Verhalten änderst, und ändere sie bewusst. - Das Wurzelmanifest enthält die von den Inline-Beispielen verwendeten Abhängigkeiten und die Liste der Arbeitsbereichsmitglieder. - Das Build-Skript findet das Markdown für den Dokumentationstest-Rahmen und trägt die zwei Ausschlusslisten, die verhindern, dass migrierte Beispiele zweimal getestet werden. - Die Konfigurationsdatei des Buches steuert, wie das Markdown in das Buch gerendert wird. - Die Konfiguration des Bauwerkzeugs definiert den Alias für den Aufgabenausführer, auf den sich die dokumentierten Befehle stützen. - Das Paket des Aufgabenausführers setzt Bauen, Testen und Linkprüfung als Unterbefehle um, sodass dieselbe Logik sowohl einem Mitwirkenden als auch der kontinuierlichen Integration dient. Wenn sich ein Befehl anders verhält als hier beschrieben, behandle die oben genannten Dateien als maßgebliche Quelle und korrigiere die Beschreibung, statt sie zu umgehen. ## Vollständige Beispiele schreiben, die Leser kopieren und ausführen können Ein Beispiel wird daran gemessen, ob jemand es in sein eigenes Projekt kopieren kann und es dort funktioniert, nicht daran, wie kurz es auf der Seite wirkt. ### Inhaltsregeln - Beispiele sind vollständig und kompilierbar, keine Fragmente. - Reiche Fehler mit dem Fehlerweitergabe-Operator der Sprache weiter, statt bei einem Fehlschlag abzustürzen, und folge dem dokumentierten Fehlerbehandlungsmuster des Projekts. - Vermeide Sammelimporte, damit ein Leser genau sehen kann, von welchen Traits und Elementen das Beispiel abhängt. - Markiere Beispiele, die einen externen Dienst oder einen Netzwerkzugang brauchen, als Nur-Kompilieren, damit die Testsuite offline lauffähig bleibt. - Verbirg Gerüstcode mit dem Präfix für verborgene Zeilen, statt ihn zu löschen, damit sich das Beispiel weiterhin kompilieren lässt. - Ziehe es vor, für ein neues Beispiel ein eigenständiges Paket anzulegen, statt eine weitere Abhängigkeit in das Wurzelmanifest aufzunehmen. ### Einen neuen Abschnitt der obersten Ebene hinzufügen Wenn du eine neue Abschnittsseite der obersten Ebene hinzufügst, füge dafür auch eine Einbindung auf der Inhaltsverzeichnisseite des Buches hinzu, an der richtigen alphabetischen Position. Diese Seite ist der Einstiegspunkt für den Leser, und ein Abschnitt, der dort nicht eingebunden ist, ist praktisch unsichtbar, auch wenn er erfolgreich gebaut wird. ## Vor der Prüfung alle Tests und die Checkliste bestehen Prüfe alles Folgende, bevor du eine Änderung zur Begutachtung einreichst oder aktualisierst, und erneut nach jeder Überarbeitung. - Die vollständige Testsuite läuft lokal fehlerfrei durch, und zwar über den dokumentierten Befehl für alle Tests statt über einen Teildurchlauf. - Die Commits sind zu einem einzigen zusammengefasst und auf den aktuellen Hauptzweig rebasiert. - Die Beschreibung enthält eine korrekte Klausel zum Schließen des Tickets, oder die Klausel wird vollständig entfernt, wenn es kein Ticket gibt. Eine falsche Ticketnummer ist schlimmer als gar keine. - Nicht gerenderte Listen stehen in sortierter Reihenfolge: Links, Verweise, Bezeichner und Manifesteinträge. Die sortierte Reihenfolge ist das, was künftige Unterschiede klein hält. - Dokumentationslinks auf externe API-Referenzseiten verwenden das Platzhaltersegment für die Version statt einer festgelegten Version, damit der Link bei der nächsten Veröffentlichung nicht verrottet. - Das Beispiel verwendet die Standard-Fehlerbehandlung des Projekts, ohne die Abkürzung, bei einem Fehlschlag abzustürzen. - Codebezeichner in der Beschreibung werden als Namen in Backticks geschrieben, die über Linkdefinitionen am Ende der Datei mit ihren Referenzseiten verknüpft sind. Beobachte nach dem Einreichen den Lauf der kontinuierlichen Integration und behebe jeden von ihr gemeldeten Fehlschlag, statt eine rote Änderung für einen Prüfer zum Sichten offen zu lassen.