Generating API Reference Docs

Relevant source files

The following files were used as context for generating this wiki page:

• agent.yml
• hugo.yaml
• CONTRIBUTING.md
• content/reference/cli/docker/README.md
• content/reference/_index.md
• layouts/partials/schema.html

The Docker documentation website (docs.docker.com) provides comprehensive reference documentation for its various APIs, including the Engine API, Docker Hub API, and Registry API. This documentation is not written directly within the docker/docs repository. Instead, it is automatically generated by vendoring content from upstream source repositories. This ensures that the documentation remains consistent with the source code and serves as a single source of truth.

The generation process relies on the Hugo static site generator and its module system. Upstream repositories provide documentation as structured data files (like YAML) or Markdown. The docker/docs build process fetches this content, processes it through specific layouts, and renders it into the final HTML reference pages. This system makes the API reference content read-only within the docker/docs repository; any required changes must be made in the corresponding upstream project.

Sources: agent.yml:40-45, CONTRIBUTING.md:73-77, hugo.yaml:222-227

Architecture and Data Flow

The documentation generation architecture is designed to decouple the content source from the presentation layer. Upstream projects own and maintain their API documentation, while the docker/docs repository consumes this content for publishing.

Sources: agent.yml:40-45, hugo.yaml:222-227

High-Level Data Flow

The following diagram illustrates the flow of documentation content from upstream repositories to the final published website.

This diagram shows that repositories like moby/moby are the source for API and CLI documentation, which is then imported and built by the Hugo process in the docker/docs repository.

Sources: agent.yml:76-82, hugo.yaml:222-287, CONTRIBUTING.md:73-81

Upstream Content Sources

Several upstream repositories provide the raw content for API and CLI reference documentation. This content is typically in the form of YAML files or Markdown. The hugo.yaml configuration file maps these sources to specific locations within the build.

Documentation Section	Upstream Repository	Source Content
Engine API Reference	moby/moby	YAML files
Docker CLI Reference	docker/cli	YAML files
Compose CLI Reference	docker/compose	YAML files
Buildx Reference	docker/buildx	Markdown files
Dockerfile Reference	moby/buildkit	Markdown file

Sources: agent.yml:76-82, hugo.yaml:230-287, content/reference/cli/docker/README.md:1-15

Build Configuration

The core of the generation process is managed by Hugo's module system, configured in hugo.yaml. This file defines which upstream repositories to import and where to "mount" their files within the site's content structure.

Sources: hugo.yaml:222-227

Hugo Module Imports

The module.imports section in hugo.yaml lists the external repositories to be used as dependencies. For each import, a mounts directive specifies which files or directories from the upstream repo should be included in the build.

The following snippet from hugo.yaml shows how the Engine API documentation is imported from the moby/moby repository.

# hugo.yaml
  imports:

    # Docker Engine API
    - path: github.com/moby/moby/api
      mounts:
        - source: docs/CHANGELOG.md
          target: content/reference/api/engine/version-history.md
        - source: docs
          target: content/reference/api/engine/version
          includeFiles: "*.yaml"

Sources: hugo.yaml:229-236

This configuration instructs Hugo to:

1. Import the github.com/moby/moby/api module.
2. Mount the docs/CHANGELOG.md file to content/reference/api/engine/version-history.md.
3. Mount all YAML files from the upstream docs directory into the content/reference/api/engine/version directory within the docker/docs project during the build.

A similar process is used for other API and CLI references, such as the Compose CLI.

# hugo.yaml
    # Compose
    - path: github.com/docker/compose/v5
      mounts:
        - source: docs/reference
          target: data/compose-cli
          includeFiles: "*.yaml"

Here, the YAML files are mounted into the data/ directory, making them available as data sources for Hugo templates.

Sources: hugo.yaml:268-273

Content Rendering Process

Once the upstream files are imported, Hugo uses layouts and templates to render them into HTML pages. The process varies slightly depending on whether the source is a Markdown file or a data file (like YAML).

Generation from Data Files (YAML)

For documentation sourced from YAML files (like the Engine API and CLI references), the process involves stub files and specialized layouts.

The following diagram shows how a YAML file is processed into a final HTML page.

1. Stub Files: The content/reference/cli/docker/ directory contains simple Markdown "stub" files. These files themselves have minimal content but are crucial for triggering Hugo to create a page at a specific URL.
2. Partial Inclusion: The stub file's primary role is to include a Hugo partial (a reusable template snippet). This partial contains the logic to parse the corresponding YAML data file.
3. Parsing and Rendering: The partial reads the data from the YAML file (e.g., command descriptions, flags, examples) and formats it into HTML.

This pattern is described in content/reference/cli/docker/README.md, which explains that stub files include /_includes/cli.md to parse the generated YAML.

Sources: content/reference/cli/docker/README.md:1-15

Page Metadata and Schema

During rendering, structured data (JSON-LD) is added to the HTML head for SEO and better machine readability. The layouts/partials/schema.html partial is responsible for generating this data. It creates a TechArticle and BreadcrumbList schema, pulling information from the page's front matter and Git history.

Key metadata includes:

• headline: The page's link title.
• description: The page's description from the front matter.
• datePublished and dateModified: Derived from Git info.
• author and publisher: Hardcoded as "Docker Inc".
• keywords: From the page's front matter.
• timeRequired: An ISO 8601 duration converted from a human-readable string like "30 minutes" in the front matter.

Sources: layouts/partials/schema.html:1-100

Updating Documentation

Because API and CLI reference documentation is vendored, it is considered read-only within the docker/docs repository. Any attempt to edit these files directly will be ineffective, as changes will be overwritten during the next build or content update.

The correct workflow for updating this documentation is:

1. Identify the correct upstream repository for the content (see table above).
2. Make the necessary changes in the source files within that upstream repository (e.g., update the YAML in moby/moby or the Markdown in docker/cli).
3. Submit a pull request to the upstream repository.
4. Once merged, the changes will be pulled into docker/docs when the Hugo module is updated.

This process is explicitly outlined in CONTRIBUTING.md and reinforced in the agent.yml configuration, which instructs automated agents not to edit vendored content.

Sources: agent.yml:40-45, CONTRIBUTING.md:73-81, content/reference/cli/docker/README.md:17-24

Summary

The generation of API reference documentation is a sophisticated, automated process that leverages Hugo Modules to vendor content from multiple upstream repositories. This ensures documentation is accurate and maintained by the teams closest to the code. The system uses a combination of data files (YAML), stub Markdown pages, and custom Hugo layouts to render the final, polished reference guides on docs.docker.com. All content is managed upstream, making the documentation in the docker/docs repository a read-only reflection of the canonical sources.