Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- Cloud Native Computing Foundation (CNCF)
- Redator técnico:
- feloy
- Nome do projeto:
- Atualização de como o site do Kubernetes serve referências de API
- Duração do projeto:
- Duração padrão (três meses)
Project description
No momento, as referências da API Kubernetes são documentos HTML grandes gerados a partir de especificações do Swagger por scripts hospedados fora do repositório do site e adicionados a esse repositório.
Por outro lado, o site de documentação do Kubernetes foi criado com o Hugo a partir da documentação escrita em formato Markdown no repositório do site, usando o tema Hugo Docsy.
O objetivo deste projeto é integrar a geração de referências da API Kubernetes ao processo de criação do site de documentação.
Especificamente, vamos nos concentrar no shortcode swaggerui, wrapper ao redor do swagger-ui, fornecido pelo tema Docsy Hugo e em ferramentas específicas, permitindo a inserção de partes da especificação da API no fluxo da documentação do Kubernetes.
Ferramentas específicas serão necessárias, já que o swagger-ui pode gerar a especificação completa descrita em um arquivo swagger, mas não partes dele (consulte 8). A API Kubernetes é muito grande para ser exibida em apenas uma parte (um exemplo de saída). Vamos considerar duas abordagens:
A primeira abordagem é criar vários arquivos swagger, um para cada grupo da API Kubernetes (core/v1, apps/v1...) das fontes disponíveis em (10), e usar esses arquivos como entrada de códigos de classificação swaggerui em locais específicos no site de documentação do Kubernetes.
A segunda abordagem é criar uma ferramenta que recebe como entrada o arquivo swagger completo da API Kubernetes encontrado em (11) e gera um novo arquivo swagger para um endpoint específico ou um número limitado de endpoints e os recursos e definições associados. Em seguida, use esses arquivos swagger como entrada de códigos curtos swaggerui em locais específicos no site de documentação do Kubernetes.
Como as fontes das especificações (10 e 11) residem em outros repositórios além das fontes da documentação, precisaremos encontrar uma maneira de atualizá-las automaticamente no repositório de documentação quando elas mudarem.
Como a documentação do Kubernetes está disponível em diferentes idiomas, vamos prestar atenção especial à possibilidade de publicar traduções para a referência da API Kubernetes.