Esta página contiene 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)
- Escritor técnico:
- feloy
- Nombre del proyecto:
- Actualizar la forma en que el sitio web de Kubernetes entrega referencias de API
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Actualmente, las referencias de la API de Kubernetes son grandes documentos HTML que se generan a partir de las especificaciones de Swagger mediante secuencias de comandos alojadas fuera del repositorio del sitio web y que luego se agregan a este repositorio del sitio web.
Por otro lado, el sitio web de documentación de Kubernetes se creó con Hugo a partir de documentación escrita en formato Markdown en el repositorio del sitio web con el tema de Docsy Hugo.
El objetivo de este proyecto es integrar la generación de referencias de la API de Kubernetes en el proceso que crea el sitio web de documentación.
Específicamente, nos enfocaremos en el código corto swaggerui, wrapper alrededor de swagger-ui, proporcionado por el tema de Docsy Hugo, y en herramientas específicas, que habilita 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 dar como resultado la especificación completa descrita en un archivo swagger, pero no partes de él (ver 8). La API de Kubernetes es demasiado grande para mostrarla solo en una parte (un ejemplo de resultado). Consideraremos dos enfoques:
El primer enfoque consiste en crear varios archivos de swagger, uno para cada grupo de API de Kubernetes (core/v1, apps/v1, ...) a partir de fuentes disponibles en (10) y usar estos archivos como entrada de códigos de clasificación swaggerui en lugares específicos del sitio web de documentación de Kubernetes.
El segundo enfoque es crear una herramienta que ingrese como entrada el archivo de estilo completo de la API de Kubernetes que se encuentra en (11) y genera un archivo de este tipo nuevo para un extremo específico o una cantidad limitada de extremos, junto con sus recursos y definiciones asociados. Luego, usa estos archivos de swagger como entrada de códigos cortos de swaggerui en lugares específicos del sitio web de documentación de Kubernetes.
Debido a que las fuentes de las especificaciones (10 y 11) se encuentran en repositorios distintos de las fuentes de la documentación, tendremos que buscar una manera de actualizarlas automáticamente en el repositorio de documentación cuando cambien.
Dado que la documentación de Kubernetes está disponible en distintos idiomas, prestaremos especial atención a la posibilidad de publicar traducciones para la referencia de la API de Kubernetes.