Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Cloud Native Computing Foundation (CNCF)
- Pisarz techniczny:
- przestępstwo
- Nazwa projektu:
- Zaktualizuj sposób, w jaki witryna Kubernetes obsługuje odwołania do interfejsów API
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Obecnie odwołania dotyczące interfejsu Kubernetes API to duże dokumenty HTML generowane na podstawie specyfikacji Swagger za pomocą skryptów hostowanych poza repozytorium witryny, a następnie dodawane do tego repozytorium witryny.
Natomiast witryna z dokumentacją Kubernetes została opracowana przez Hugo na podstawie dokumentacji w formacie Markdown dostępnej w repozytorium witryny i przy użyciu motywu Dokumentyy Hugo.
Celem tego projektu jest zintegrowanie generowania odniesień do interfejsu Kubernetes API w procesie tworzenia strony z dokumentacją.
Skupimy się na krótkim kodzie swaggerui zapewnianym przez motyw swagger-ui zapewnianym przez motyw Docsy Hugo oraz na konkretnych narzędziach, które umożliwiają wstawianie części specyfikacji interfejsu API w kierunku dokumentacji Kubernetes.
Potrzebne będą specjalne narzędzia, ponieważ swagger-ui może wygenerować pełną specyfikację opisaną w pliku z treściami, ale nie jego części (patrz 8). Interfejs Kubernetes API jest za duży, aby można go było wyświetlić tylko w jednej części (przykład danych wyjściowych). Rozważymy 2 podejścia:
pierwszym sposobem jest utworzenie kilku plików dodatkowych, po jednym dla każdej grupy Kubernetes API (core/v1, apps/v1 itd.) ze źródeł dostępnych pod adresem (10), i wykorzystanie tych plików jako danych wejściowych do kodu sortowania swaggerui w określonych miejscach na stronie z dokumentacją Kubernetes.
Drugim sposobem jest stworzenie narzędzia, które jako dane wejściowe całego pliku z wyglądami Kubernetes API znajduje się na stronie (11) i wygeneruje nowy plik tego typu dla określonego punktu końcowego lub ograniczonej liczby punktów końcowych oraz powiązanych z nim zasobów i definicji, a potem wykorzystuje te pliki jako dane wejściowe w określonych miejscach na stronie z dokumentacją Kubernetes.
Źródła specyfikacji (10 i 11) znajdują się w innych repozytoriach niż źródła dokumentacji, dlatego będziemy musieli znaleźć sposób na ich automatyczne aktualizowanie w repozytorium dokumentacji, gdy się zmienią.
Dokumentacja Kubernetes jest dostępna w różnych językach, dlatego zwrócimy szczególną uwagę na możliwość publikowania tłumaczeń materiałów referencyjnych Kubernetes API.