En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Cloud Native Computing Foundation (CNCF)
- Redactor técnico:
- feloy
- Nombre del proyecto:
- Actualiza la forma en que el sitio web de Kubernetes entrega referencias de la API
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Actualmente, las referencias de la API de Kubernetes son documentos HTML grandes que se generan a partir de las especificaciones de Swagger mediante secuencias de comandos alojadas fuera del repositorio del sitio web y, luego, se agregan a este repositorio.
Por otro lado, el sitio web de documentación de Kubernetes se compila con Hugo a partir de la documentación escrita en formato Markdown en el repositorio del sitio web, con el tema Docsy Hugo.
El objetivo de este proyecto es integrar la generación de las referencias de la API de Kubernetes en el proceso que compila el sitio web de documentación.
Específicamente, nos enfocaremos en el código corto de swaggerui, wrapper de swagger-ui, proporcionado por el tema de Documentos de Hugo y en herramientas específicas, que permiten la inserción de partes de la especificación de la API en el flujo de la documentación de Kubernetes.
Se necesitarán herramientas específicas, ya que swagger-ui puede generar la especificación completa descrita en un archivo de Swagger, pero no partes de él (consulta la sección 8). La API de Kubernetes es demasiado grande para mostrarla solo de una parte (un ejemplo de resultado). Consideraremos dos enfoques:
El primer enfoque es crear varios archivos de Swagger, uno para cada grupo de la API de Kubernetes (core/v1, apps/v1, etc.) a partir de las fuentes disponibles en (10) y usar estos archivos como entrada de los códigos de clasificación de swaggerui en lugares específicos del sitio web de documentación de Kubernetes.
El segundo enfoque es crear una herramienta que tome como entrada el archivo swagger completo de la API de Kubernetes que se encuentra en (11) y genere un nuevo archivo swagger para un extremo específico o una cantidad limitada de extremos, y sus recursos y definiciones asociados. Luego, usa estos archivos swagger como entrada de códigos cortos de swaggerui en lugares específicos del sitio web de documentación de Kubernetes.
Como las fuentes de las especificaciones (10 y 11) residen en otros repositorios que las fuentes de la documentación, necesitaremos encontrar una forma de actualizarlas automáticamente en el repositorio de documentación cuando cambien.
Dado que la documentación de Kubernetes está disponible en diferentes idiomas, prestaremos especial atención a la posibilidad de publicar traducciones para la referencia de la API de Kubernetes.