Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- Cloud Native Computing Foundation (CNCF)
- Rédacteur technique:
- feloy
- Nom du projet:
- Mise à jour de la façon dont le site Web Kubernetes diffuse les références d'API
- Durée du projet:
- Durée standard (trois mois)
Project description
Actuellement, les références de l'API Kubernetes sont de grands documents HTML générés à partir des spécifications Swagger par des scripts hébergés en dehors du dépôt du site Web, puis ajoutés à ce dépôt.
D'autre part, le site Web de documentation Kubernetes est créé avec Hugo à partir de la documentation écrite au format Markdown dans le dépôt du site Web, à l'aide du thème Hugo Docsy.
L'objectif de ce projet est d'intégrer la génération des références de l'API Kubernetes au processus de création du site Web de documentation.
Plus précisément, nous allons nous concentrer sur le shortcode swaggerui, wrapper autour de swagger-ui, fourni par le thème Hugo Docsy, et sur des outils spécifiques permettant d'insérer des parties de la spécification de l'API dans le flux de la documentation Kubernetes.
Des outils spécifiques seront nécessaires, car swagger-ui peut générer la spécification complète décrite dans un fichier Swagger, mais pas en partie (voir la section 8). L'API Kubernetes est trop volumineuse pour être affichée en une seule partie (exemple de sortie). Nous allons envisager deux approches:
La première approche consiste à créer plusieurs fichiers Swagger, un pour chaque groupe d'API Kubernetes (core/v1, apps/v1, etc.) à partir des sources disponibles sur (10) et à utiliser ces fichiers comme entrée des codes de tri swaggerui à des emplacements spécifiques sur le site Web de documentation Kubernetes.
La deuxième approche consiste à créer un outil qui reçoit en entrée le fichier swagger complet de l'API Kubernetes disponible à l'adresse (11) et qui produit un nouveau fichier swagger pour un point de terminaison spécifique ou un nombre limité de points de terminaison, ainsi que les ressources et définitions associées. Vous pouvez ensuite utiliser ces fichiers swagger comme entrée de codes courts swaggerui à des emplacements spécifiques sur le site Web de la documentation Kubernetes.
Étant donné que les sources des spécifications (10 et 11) résident dans d'autres référentiels que les sources de la documentation, nous devrons trouver un moyen de les mettre à jour automatiquement dans le référentiel de documentation lorsqu'elles changent.
Comme la documentation Kubernetes est disponible dans différentes langues, nous allons accorder une attention particulière à la possibilité de publier des traductions de la documentation de référence de l'API Kubernetes.