Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Cloud Native Computing Foundation (CNCF)
- Rédacteur technique:
- féloy
- Nom du projet:
- Mettre à jour la façon dont le site Web Kubernetes diffuse des références d'API
- Durée du projet:
- Durée standard (3 mois)
Project description
Actuellement, les références de l'API Kubernetes sont de grands documents HTML générés à partir de spécifications Swagger par des scripts hébergés en dehors du dépôt de sites Web, puis ajoutés à celui-ci.
D'un autre côté, le site Web de documentation de 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 Docsy Hugo.
L'objectif de ce projet est d'intégrer la génération des références de l'API Kubernetes dans le processus de création du site Web de documentation.
Plus précisément, nous nous concentrerons sur le code court swaggerui, wrapper autour de swagger-ui, fourni par le thème Docsy Hugo et sur des outils spécifiques, qui permettent d'insérer des parties de la spécification d'API dans le flux de la documentation Kubernetes.
Des outils spécifiques sont nécessaires, car swagger-ui est en mesure de générer la spécification complète décrite dans un fichier swagger, mais pas certaines de celui-ci (voir 8). L'API Kubernetes est trop volumineuse pour être affichée dans une seule partie(exemple de résultat). Nous envisagerons deux approches:
La première approche consiste à créer plusieurs fichiers swaggerui, un pour chaque groupe d'API Kubernetes (core/v1, apps/v1, ...) à partir des sources disponibles à l'adresse (10) et d'utiliser ces fichiers comme entrée de code de tri swaggerui à des endroits spécifiques du site Web de la documentation Kubernetes.
La deuxième approche consiste à créer un outil qui reçoit en entrée le fichier de fantaisie complet de l'API Kubernetes disponible à l'adresse (11) et qui génère un nouveau fichier de fantaisie pour un point de terminaison spécifique ou un nombre limité de points de terminaison, ainsi que les ressources et définitions associées. Ensuite, utilisez ces fichiers fantaisistes comme entrée de codes abrégés swaggerui à des endroits spécifiques du site Web de la documentation Kubernetes.
Comme les sources des spécifications (10 et 11) se trouvent dans d'autres référentiels que les sources de la documentation, nous devons trouver un moyen de les mettre automatiquement à jour dans le référentiel de documentation lorsqu'elles changent.
La documentation Kubernetes étant disponible dans plusieurs langues, nous accorderons une attention particulière à la possibilité de publier des traductions pour la documentation de référence de l'API Kubernetes.