Generating CLI Reference Docs
Relevant source files
The following files were used as context for generating this wiki page:The Command Line Interface (CLI) reference documentation is a critical part of the Docker documentation suite. Unlike narrative guides, the CLI reference is not manually written within the docker/docs repository. Instead, it is automatically generated and vendored from upstream source code repositories to ensure accuracy and consistency with the tools themselves. This system treats the source code as the single source of truth for command descriptions, usage, and examples.
This process involves generating structured YAML data files from the upstream repositories and using Hugo templates to render these files into the final HTML documentation pages. Any contributions or corrections to the CLI reference must be made in the corresponding upstream project, not directly in the documentation repository.
Sources: content/reference/cli/docker/README.md:8-11, CONTRIBUTING.md:60-62, agent.yml:32-37
Architecture Overview
The generation of CLI reference documentation follows a multi-stage pipeline that starts with the source code of Docker's various CLI tools and ends with published pages on the documentation website.
The following diagram illustrates the high-level data flow for generating CLI reference documentation.
This diagram shows that content originates in upstream repositories, is processed into YAML files, and then built into the final website using Hugo templates within the docker/docs repository.
Sources: content/reference/cli/docker/README.md:8-11, CONTRIBUTING.md:60-67, agent.yml:102-108
Data Sources and Generation
Upstream Repositories
The source of truth for all CLI reference documentation resides in the respective upstream repositories for each tool. These repositories contain not only the command's implementation but also the embedded documentation that will be extracted.
| Content Type | Upstream Repository |
|---|---|
| Docker CLI commands | docker/cli |
| Docker Compose commands | docker/compose |
| Buildx commands | docker/buildx |
| Model Runner commands | docker/model-runner |
The documentation is composed of two main parts from these repositories:
- Description and Usage: Pulled directly from the CLI source code.
- Extended Description and Examples: Pulled from Markdown files located within the
docs/reference/commandlinedirectory of the upstream repository.
Sources: content/reference/cli/docker/README.md:15-23, CONTRIBUTING.md:63-67, agent.yml:102-108
YAML File Generation
A process, which is noted as being "in flux", generates YAML files from the upstream repositories. These YAML files serve as an intermediate, structured data format that Hugo can easily consume. After generation, these files are placed into directories like _data/engine-cli within the docker/docs repository.
The structure of these YAML files contains all the necessary information to build a complete reference page for a command.
| YAML Key | Description | Example from Template |
|---|---|---|
short | A brief, one-line description of the command. | {{ with $data.short }} |
usage | The command's usage syntax. | <code>{{ . }}</code> |
long | The extended description, often multi-paragraph. | {{ with $data.long }} |
options | An array of objects, each describing a command-line flag. | {{ range . }} |
examples | Markdown content containing usage examples. | {{ with $data.examples }} |
deprecated | A boolean indicating if the command is deprecated. | {{ if $data.deprecated }} |
experimental | A boolean indicating if the command is experimental. | {{ if or $data.experimental ... }} |
aliases | A string of command aliases. | {{ with $data.aliases }} |
Sources: content/reference/cli/docker/README.md:25-31, layouts/_default/scout-cli.html:4-9, 52-59, 102-105, 150-153
Rendering with Hugo
The final HTML pages for the CLI reference are rendered by the Hugo static site generator using specific layout templates. These templates are designed to parse the generated YAML files and format them into a readable and consistent documentation page.
Template Logic
A template such as layouts/_default/scout-cli.html (which serves as a good example for cli.html) is responsible for this rendering. It accesses the YAML data via site.Data and maps the fields to HTML elements.
The rendering flow from YAML to HTML is as follows:
This diagram shows how a Hugo template takes a single YAML data file and uses its contents to populate various sections of the final HTML page.
The template logic includes:
- Displaying the
shortdescription andusagein a top-level table. - Rendering the
longdescription as the main body content. - Iterating through the
optionsarray to create a detailed table of all available flags, their defaults, and descriptions. - Displaying badges for command attributes like
deprecated,experimental,kubernetes, andswarm. - Rendering the
examplessection.
Sources: layouts/_default/scout-cli.html:3-9, 52-73, 102-148, 163-174
Update Process
Updating the CLI reference documentation is a process managed by maintainers and requires regenerating the YAML files from the source repositories.
The workflow for an update is as follows:
This process ensures that the documentation always reflects the state of the specified release branch of the tool. Direct edits to the YAML files or the generated Markdown stubs in the docker/docs repository are not the correct approach.
Sources: content/reference/cli/docker/README.md:25-31, CONTRIBUTING.md:58-67
Conclusion
The system for generating CLI reference documentation is a robust mechanism designed to maintain synchronization between the code and the docs. By treating the upstream repositories as the single source of truth and using an automated generation process, the documentation remains accurate and up-to-date. This "vendored" approach means that the community must contribute to the respective upstream projects to improve the CLI documentation, reinforcing the link between the tools and their reference materials.
Sources: agent.yml:32-37, CONTRIBUTING.md:60-62