Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- Cloud Native Computing Foundation (CNCF)
- Technischer Redakteur:
- Feloy
- Projektname:
- Aktualisieren, wie API-Referenzen auf der Kubernetes-Website bereitgestellt werden
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Derzeit sind die Kubernetes API-Referenzen große HTML-Dokumente, die anhand von Swagger-Spezifikationen von Skripts generiert und außerhalb des Website-Repositorys gehostet und dann dem Website-Repository hinzugefügt werden.
Auf der anderen Seite wurde die Kubernetes-Dokumentationswebsite mit Hugo aus einer Dokumentation im Markdown-Format im Website-Repository erstellt, die auf dem Docsy-Hugo-Theme basiert.
Ziel dieses Projekts ist es, die Generierung von Kubernetes API-Referenzen in den Prozess zum Erstellen der Dokumentationswebsite zu integrieren.
Dabei konzentrieren wir uns insbesondere auf den Kurzcode „swaggerui“, den Wrapper um swagger-ui, der vom Docsy Hugo-Theme zur Verfügung gestellt wird, und auf bestimmte Tools, mit denen Teile der API-Spezifikation in den Ablauf der Kubernetes-Dokumentation eingefügt werden können.
Dafür sind spezielle Tools erforderlich, da swagger-ui die vollständige Spezifikation ausgeben kann, die in einer Swagger-Datei beschrieben ist, jedoch nicht Teile davon (siehe 8). Die Kubernetes API ist zu groß, um nur in einem Teil angezeigt zu werden (Beispiel für die Ausgabe). Wir betrachten zwei Ansätze:
Der erste Ansatz besteht darin, mehrere Swagger-Dateien zu erstellen, eine für jede Kubernetes API-Gruppe (core/v1, apps/v1, ...) aus Quellen, 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 sowie die zugehörigen Ressourcen und Definitionen ausgibt. Diese Swagger-Dateien dann als Eingabe von Swaggerui-Kurzcodes an bestimmten Stellen auf der Kubernetes-Dokumentationswebsite verwenden.
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 automatisch im Dokumentations-Repository zu aktualisieren, wenn sie sich ändern.
Da die Kubernetes-Dokumentation in verschiedenen Sprachen verfügbar ist, wird die Möglichkeit, Übersetzungen für die Kubernetes API-Referenz zu veröffentlichen, besonders beachtet.