Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- Cloud Native Computing Foundation (CNCF)
- Technischer Redakteur:
- feloy
- Projektname:
- API-Referenzen auf der Kubernetes-Website aktualisieren
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Derzeit sind die Referenzen der Kubernetes API große HTML-Dokumente, die aus Swagger-Spezifikationen mithilfe von Scripts generiert und außerhalb des Website-Repositorys gehostet und dann diesem Repository hinzugefügt werden.
Die Kubernetes-Dokumentationswebsite hingegen wird mit Hugo aus der im Website-Repository im Markdown-Format geschriebenen Dokumentation erstellt. Dabei wird das Docsy Hugo-Design verwendet.
Ziel dieses Projekts ist es, die Generierung der Kubernetes API-Referenzen in den Prozess einzubinden, mit dem die Dokumentationswebsite erstellt wird.
Wir konzentrieren uns insbesondere auf den Swaggerui-Kurzcode, den Wrapper um swagger-ui, der vom Docsy Hugo-Design bereitgestellt wird, und auf bestimmte Tools, die es ermöglichen, Teile der API-Spezifikation in den Ablauf der Kubernetes-Dokumentation einzufügen.
Es sind spezielle Tools erforderlich, da swagger-ui die vollständige in einer Swagger-Datei beschriebene Spezifikation ausgeben kann, aber keine Teile davon (siehe 8). Die Kubernetes API ist zu groß, um nur in einem Teil angezeigt zu werden (Beispiel für eine Ausgabe). Wir werden zwei Ansätze in Betracht ziehen:
Der erste Ansatz besteht darin, mehrere Swagger-Dateien für jede Kubernetes API-Gruppe (core/v1, apps/v1, ...) aus Quellen zu erstellen, die unter (10) verfügbar sind, und diese Dateien als Eingabe von Swaggerui-Sortiercodes an bestimmten Stellen auf der Kubernetes-Dokumentationswebsite zu verwenden.
Der zweite Ansatz besteht darin, ein Tool zu erstellen, das die vollständige Swagger-Datei der Kubernetes API unter (11) als Eingabe erhält und eine neue Swagger-Datei für einen bestimmten Endpunkt oder eine begrenzte Anzahl von Endpunkten und die zugehörigen Ressourcen und Definitionen ausgibt. Diese Swagger-Dateien werden dann an bestimmten Stellen auf der Kubernetes-Dokumentationswebsite als Eingabe für SwaggerUI-Kurzcodes verwendet.
Da sich die Quellen der Spezifikationen (10 und 11) in anderen Repositories als die Quellen der Dokumentation befinden, müssen wir eine Möglichkeit finden, sie bei Änderungen automatisch im Dokumentationsverzeichnis zu aktualisieren.
Da die Kubernetes-Dokumentation in verschiedenen Sprachen verfügbar ist, achten wir besonders auf die Möglichkeit, Übersetzungen für die Kubernetes API-Referenz zu veröffentlichen.