API Specification Files
Relevant source files
The following files were used as context for generating this wiki page:
The Docker documentation project utilizes structured data files, primarily in YAML format, to automatically generate and maintain reference documentation for its various APIs and Command-Line Interfaces (CLIs). This approach ensures that the documentation is consistent, accurate, and directly tied to the source code or an authoritative specification. These files act as a single source of truth, from which the Hugo static site generator builds the final HTML pages for docs.docker.com.
This system distinguishes between locally managed content and "vendored" content, which is sourced from upstream repositories. Many of the specification files fall into this latter category, meaning they are read-only within the docker/docs repository. Any necessary corrections must be made in the corresponding upstream project. This ensures that the documentation accurately reflects the behavior of the tool it describes.
Sources: agent.yml:32-40, CONTRIBUTING.md:65-69
Documentation Generation Architecture
The documentation generation process relies on a workflow where specification files, often generated from upstream codebases, are consumed by the Hugo build process to create reference pages. This is particularly true for CLI and API reference material.
Sources: agent.yml:32-40, content/reference/cli/docker/README.md:1-6
Upstream Content Flow
The diagram below illustrates how content from upstream repositories is processed into documentation pages.
This diagram shows that various upstream repositories are the source for a generation process that creates YAML specification files. These files are then used by the Hugo build system within the docker-docs repository to produce the final documentation.
Sources: agent.yml:64-71, CONTRIBUTING.md:65-74
Types of Specification Files
The repository uses several types of structured data files to manage documentation content.
| File Type | Location | Purpose | Source |
|---|---|---|---|
| API Specifications | content/reference/api/ | Defines endpoints and schemas for various Docker APIs, such as the Hub and Registry APIs. | content/reference/_index.md |
| CLI Command Specs | _data/engine-cli/ | YAML files generated from CLI source code, detailing command usage, descriptions, and examples. | content/reference/cli/docker/README.md |
| Page Metadata | data/frontmatter.yaml | Augments pages (especially generated ones) with metadata like description and keywords. | data/frontmatter.yaml |
CLI Reference Generation
The reference documentation for Docker CLI commands is not written manually. Instead, it is generated from YAML files that are sourced from upstream repositories like docker/cli and docker/compose.
Sources: CONTRIBUTING.md:65-74, content/reference/cli/docker/README.md:1-6
Process
- Source Extraction: The
DescriptionandUsagesections for a command are extracted directly from the CLI source code. - Markdown Inclusion: The
Extended DescriptionandExamplessections are parsed from Markdown files located within the upstream repository'sdocs/reference/commandlinedirectory. - YAML Generation: This combined information is compiled into YAML files.
- Local Integration: The generated YAML files are placed in the
_data/engine-clidirectory of thedocker-docsrepository. - Page Rendering: Stub files in
content/reference/cli/docker/include a partial that parses these YAML files to generate the final HTML pages.
The diagram below visualizes this data flow for a single command.
API Reference Pages
The project provides reference documentation for several APIs, which are listed on the main reference page. These are driven by specification files.
Sources: content/reference/_index.md:38-59
Available APIs
The documentation includes references for the following APIs, each likely corresponding to a specification file:
- Engine API: The main API for Docker, providing programmatic access to the daemon.
- Docker Hub API: API to interact with Docker Hub.
- DVP Data API: API for Docker Verified Publishers to fetch analytics data.
- Registry API: API for the Docker Registry.
The presence of content/reference/api/hub/latest.yaml and content/reference/api/registry/latest.yaml confirms that YAML files are used to define these APIs.
Sources: content/reference/_index.md:42-59, content/reference/api/hub/latest.yaml, content/reference/api/registry/latest.yaml
Metadata Augmentation
For pages generated from specification files, it's not always possible to add front matter directly to the source. The data/frontmatter.yaml file solves this by allowing metadata to be associated with a page path.
This file lets contributors add description and keywords to pages without modifying the original file, which is crucial for vendored or generated content.
Example Configuration
The following snippet from data/frontmatter.yaml shows how metadata is applied to the generated Dockerfile reference page.
# data/frontmatter.yaml
reference/dockerfile.md:
description: |
Find all the available commands you can use in a Dockerfile
and learn how to use them, including COPY, ARG, ENTRYPOINT, and more.
keywords: |
dockerfile, docker file, docker copy, dockerfile exec, docker entrypoint,
dockerfile entrypoint, dockerfile arg, docker args, entrypoint, shell dockerfile
Sources: data/frontmatter.yaml:1-10, 26-34
Managing Upstream Changes
Because much of the reference documentation is generated from upstream sources, a special workflow is required when updates are needed. The agent.yml file defines an automated "coordinator" agent that can identify whether a requested change is local or requires an update to an upstream repository.
If a broken link or incorrect information originates from a generated file (e.g., in content/reference/cli/), the fix must be applied in the source repository (e.g., docker/cli, moby/moby). The coordinator agent is designed to identify these cases and prevent developers from attempting to edit the read-only files in the docker-docs repository directly.
The following sequence diagram shows how a request to fix a CLI flag is handled.
Sources: agent.yml:43-71, CONTRIBUTING.md:65-74