docker / docker/cli

Documentation generation without internet connectivity

Open
#4,212 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

kind/feature status/0-triage
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Description

When trying to build the docker cli man pages, the scripts for building the man pages (since v23.0.0) require an internet connection because the handful of packages needed to generate the man pages are not vendored and thus need to be pulled at build time. The same applies for the yaml and markdown docs.

This is not possible in the build environment of some distributions (at the very least, openSUSE doesn't permit internet access to build machines but I suspect this is true for a fair number of distributions). The net result is that we cannot release any version of Docker >=23.0.0 at the moment because we cannot package the man pages for Docker.

I've spent a while trying to figure out a way to work around this in various ways, but it seems the simplest solution would be to back to vendoring the packages. This change was added in #3381, but it seems like the purpose of that PR was to simply add a way of building the documentation during CI to validate the build works. The switch to requiring internet access for the build doesn't seem necessary to me and there was no discussion in the PR about this change (indicating that the downstream impact of this change wasn't noticed at the time).

Would you accept a PR that switches back to vendoring the packages needed for documentation generation, removing the need for internet access?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the scripts used to build the Docker CLI man pages and the YAML and Markdown documentation, then review the changes in #3381 to identify the packages currently fetched at build time. Done means the documentation generation process can build successfully without internet access, including in a distribution packaging environment.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
build-system, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.