Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- Cloud Native Computing Foundation (CNCF)
- Pisarz techniczny:
- feloy
- Nazwa projektu:
- Zaktualizuj sposób, w jaki witryna Kubernetes obsługuje odwołania do interfejsu API
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Obecnie odwołania do interfejsu Kubernetes API to duże dokumenty HTML wygenerowane na podstawie specyfikacji Swagger za pomocą skryptów hostowanych poza repozytorium witryny, a następnie dodanych do tego repozytorium.
Z drugiej strony witryna z dokumentacją Kubernetes została stworzona we współpracy z Hugo na podstawie dokumentacji zapisanej w formacie Markdown w repozytorium witryny i motywu Dokumentów Hugo.
Celem tego projektu jest zintegrowanie generowania odwołań do interfejsu Kubernetes API z procesem tworzenia witryny z dokumentacją.
W szczególności skupimy się na krótkim kodzie Swaggerui obejmującym interfejs swagger-ui udostępniany przez motyw Dokumentów Hugo oraz na określonych narzędziach, które umożliwiają wstawianie części specyfikacji API w przepływie dokumentacji Kubernetes.
Potrzebne będą specjalne narzędzia, ponieważ swagger-ui może wygenerować pełną specyfikację opisaną w pliku swagger, ale nie jej części (patrz punkt 8). Interfejs Kubernetes API jest za duży, aby można go było wyświetlić tylko w jednej części (przykładowe dane wyjściowe). Rozważymy 2 podejścia:
Pierwsze podejście polega na utworzeniu kilku plików swagger, po jednym dla każdej grupy interfejsu API Kubernetes (core/v1, apps/v1, itd.) ze źródeł dostępnych w (10) i użyciu tych plików jako danych wejściowych sortcodes swaggerui w określonych miejscach na stronie internetowej dokumentacji Kubernetes.
Drugie podejście polega na utworzeniu narzędzia, które jako dane wejściowe otrzymuje pełny plik swagger interfejsu API Kubernetes (znajdujący się w (11)) i wyprowadza nowy plik swagger dla konkretnego punktu końcowego lub ograniczonej liczby punktów końcowych wraz z powiązanymi zasobami i definicjami, a następnie używa tych plików swagger jako danych wejściowych do skrótów swaggerui w określonych miejscach na stronie internetowej dokumentacji Kubernetes.
Źródła specyfikacji (10 i 11) znajdują się w innych repozytoriach niż źródła dokumentacji, dlatego musimy znaleźć sposób na ich automatyczne aktualizowanie w repozytorium dokumentacji po wprowadzeniu zmian.
Dokumentacja Kubernetes jest dostępna w różnych językach, dlatego zwrócić szczególną uwagę na możliwość opublikowania tłumaczeń dla dokumentacji Kubernetes API.