This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Cloud Native Computing Foundation (CNCF)
- Technical writer:
- feloy
- Project name:
- Update how the Kubernetes website serves API references
- Project length:
- Standard length (3 months)
Project description
Currently, the Kubernetes API references are large HTML documents generated from Swagger specs by scripts hosted outside the website repository, then added into this website repository.
On another side, the Kubernetes documentation website is built with Hugo from documentation written in Markdown format in the website repository, using the Docsy Hugo theme.
The goal of this project is to integrate the generation of the Kubernetes API references into the process that builds the documentation website.
Specifically, we will focus on the swaggerui shortcode, wrapper around swagger-ui, provided by the Docsy Hugo theme and on specific tooling, enabling the insertion of parts of the API specification in the flow of the Kubernetes documentation.
Specific tooling will be needed as swagger-ui is able to output the complete specification described in a swagger file, but not parts of it (see 8). The Kubernetes API is too big to be displayed in one part only (an example of output). We will consider two approaches:
first approach is to create several swagger files, one for each Kubernetes API group (core/v1, apps/v1, ...) from sources available at (10) and use these files as input of swaggerui sortcodes at specific places in the Kubernetes documentation website,
second approach is to create a tool that gets as input the complete swagger file of the Kubernetes API found at (11) and outputs a new swagger file for a specific endpoint or a limited number of endpoints, and its associated resources and definitions, then use these swagger files as input of swaggerui shortcodes at specific places in the Kubernetes documentation website.
As the sources of the specifications (10 and 11) reside in other repositories than the sources of the documentation, we will need to find a way to automatically update them in the documentation repository when they change.
As the Kubernetes documentation is available in different languages, we will pay special attention to the possibility of publishing translations for the Kubernetes API reference.