docs: generate markdown

Keep frontmatter for docker, dockerd and index markdown files. Also needs to move cli.md > docker.md before generation and then move it back because cli.md is needed for yaml generation on docs website: #3924 (comment) Signed-off-by: Kevin Alvarez <crazy-max@users.noreply.github.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
docker · Jan 6, 2023 · 79c9e52 · 79c9e52
1 parent 186dcf3
commit 79c9e52
Show file tree

Hide file tree

Showing 194 changed files with 3,439 additions and 2,786 deletions.
diff --git a/Makefile b/Makefile
@@ -90,6 +90,10 @@ authors: ## generate AUTHORS file from git history
 manpages: ## generate man pages from go source and markdown
 	scripts/docs/generate-man.sh
 
+.PHONY: mddocs
+mddocs: ## generate markdown files from go source
+	scripts/docs/generate-md.sh
+
 .PHONY: yamldocs
 yamldocs: ## generate documentation YAML files consumed by docs repo
 	scripts/docs/generate-yaml.sh

diff --git a/docker.Makefile b/docker.Makefile
@@ -103,6 +103,10 @@ authors: ## generate AUTHORS file from git history
 manpages: build_docker_image ## generate man pages from go source and markdown
 	$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make manpages
 
+.PHONY: mddocs
+mddocs: build_docker_image ## generate markdown files from go source
+	$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make mddocs
+
 .PHONY: yamldocs
 yamldocs: build_docker_image ## generate documentation YAML files consumed by docs repo
 	$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make yamldocs

diff --git a/docs/generate.go b/docs/generate.go
@@ -10,17 +10,20 @@ import (
 	"os"
 
 	clidocstool "github.com/docker/cli-docs-tool"
+	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/command/commands"
+	"github.com/pkg/errors"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
 const defaultSourcePath = "docs/reference/commandline/"
 
 type options struct {
-	source string
-	target string
+	source  string
+	target  string
+	formats []string
 }
 
 func gen(opts *options) error {
@@ -34,6 +37,10 @@ func gen(opts *options) error {
 		Use:   "docker [OPTIONS] COMMAND [ARG...]",
 		Short: "The base command for the Docker CLI.",
 	}
+	clientOpts, _, _ := cli.SetupRootCommand(cmd)
+	if err := dockerCLI.Initialize(clientOpts); err != nil {
+		return err
+	}
 	commands.AddCommands(cmd, dockerCLI)
 
 	c, err := clidocstool.New(clidocstool.Options{
@@ -46,17 +53,36 @@ func gen(opts *options) error {
 		return err
 	}
 
-	return c.GenYamlTree(cmd)
+	for _, format := range opts.formats {
+		switch format {
+		case "md":
+			if err = c.GenMarkdownTree(cmd); err != nil {
+				return err
+			}
+		case "yaml":
+			if err = c.GenYamlTree(cmd); err != nil {
+				return err
+			}
+		default:
+			return errors.Errorf("unknown format %q", format)
+		}
+	}
+
+	return nil
 }
 
 func run() error {
 	opts := &options{}
 	flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
 	flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
 	flags.StringVar(&opts.target, "target", defaultSourcePath, "Docs target folder")
+	flags.StringSliceVar(&opts.formats, "formats", []string{}, "Format (md, yaml)")
 	if err := flags.Parse(os.Args[1:]); err != nil {
 		return err
 	}
+	if len(opts.formats) == 0 {
+		return errors.New("Docs format required")
+	}
 	return gen(opts)
 }
 

diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md
@@ -1,25 +1,22 @@
----
-title: "attach"
-description: "The attach command description and usage"
-keywords: "attach, running, container"
----
-
 # attach
 
-```markdown
-Usage: docker attach [OPTIONS] CONTAINER
-
+<!---MARKER_GEN_START-->
 Attach local standard input, output, and error streams to a running container
 
-Aliases:
-  docker container attach, docker attach
+### Aliases
 
-Options:
-      --detach-keys string   Override the key sequence for detaching a container
-      --help                 Print usage
-      --no-stdin             Do not attach STDIN
-      --sig-proxy            Proxy all received signals to the process (default true)
-```
+`docker container attach`, `docker attach`
+
+### Options
+
+| Name            | Type     | Default | Description                                         |
+|:----------------|:---------|:--------|:----------------------------------------------------|
+| `--detach-keys` | `string` |         | Override the key sequence for detaching a container |
+| `--no-stdin`    |          |         | Do not attach STDIN                                 |
+| `--sig-proxy`   |          |         | Proxy all received signals to the process           |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
@@ -1,64 +1,49 @@
----
-title: "build"
-description: "The build command description and usage"
-keywords: "build, docker, image"
----
-
 # build
 
-```markdown
-Usage:  docker build [OPTIONS] PATH | URL | -
-
+<!---MARKER_GEN_START-->
 Build an image from a Dockerfile
 
-Aliases:
-  docker image build, docker build, docker buildx build, docker builder build
-
-Options:
-      --add-host value          Add a custom host-to-IP mapping (host:ip) (default [])
-      --build-arg value         Set build-time variables (default [])
-      --cache-from value        Images to consider as cache sources (default [])
-      --cgroup-parent string    Optional parent cgroup for the container
-      --compress                Compress the build context using gzip
-      --cpu-period int          Limit the CPU CFS (Completely Fair Scheduler) period
-      --cpu-quota int           Limit the CPU CFS (Completely Fair Scheduler) quota
-  -c, --cpu-shares int          CPU shares (relative weight)
-      --cpuset-cpus string      CPUs in which to allow execution (0-3, 0,1)
-      --cpuset-mems string      MEMs in which to allow execution (0-3, 0,1)
-      --disable-content-trust   Skip image verification (default true)
-  -f, --file string             Name of the Dockerfile (Default is 'PATH/Dockerfile')
-      --force-rm                Always remove intermediate containers
-      --help                    Print usage
-      --iidfile string          Write the image ID to the file
-      --isolation string        Container isolation technology
-      --label value             Set metadata for an image (default [])
-  -m, --memory string           Memory limit
-      --memory-swap string      Swap limit equal to memory plus swap: '-1' to enable unlimited swap
-      --network string          Set the networking mode for the RUN instructions during build
-                                'bridge': use default Docker bridge
-                                'none': no networking
-                                'container:<name|id>': reuse another container's network stack
-                                'host': use the Docker host network stack
-                                '<network-name>|<network-id>': connect to a user-defined network
-      --no-cache                Do not use cache when building the image
-  -o, --output                  Output destination (format: type=local,dest=path)
-      --pull                    Always attempt to pull a newer version of the image
-      --progress                Set type of progress output (only if BuildKit enabled) (auto, plain, tty).
-                                Use plain to show container output
-  -q, --quiet                   Suppress the build output and print image ID on success
-      --rm                      Remove intermediate containers after a successful build (default true)
-      --secret                  Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret"
-      --security-opt value      Security Options (default [])
-      --shm-size bytes          Size of /dev/shm
-                                The format is `<number><unit>`. `number` must be greater than `0`.
-                                Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
-                                or `g` (gigabytes). If you omit the unit, the system uses bytes.
-      --squash                  Squash newly built layers into a single new layer (**Experimental Only**)
-      --ssh                     SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])
-  -t, --tag value               Name and optionally a tag in the 'name:tag' format (default [])
-      --target string           Set the target build stage to build.
-      --ulimit value            Ulimit options (default [])
-```
+### Aliases
+
+`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
+
+### Options
+
+| Name                                | Type          | Default   | Description                                                       |
+|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
+| [`--add-host`](#add-host)           | `list`        |           | Add a custom host-to-IP mapping (`host:ip`)                       |
+| [`--build-arg`](#build-arg)         | `list`        |           | Set build-time variables                                          |
+| [`--cache-from`](#cache-from)       | `stringSlice` |           | Images to consider as cache sources                               |
+| [`--cgroup-parent`](#cgroup-parent) | `string`      |           | Optional parent cgroup for the container                          |
+| `--compress`                        |               |           | Compress the build context using gzip                             |
+| `--cpu-period`                      | `int64`       | `0`       | Limit the CPU CFS (Completely Fair Scheduler) period              |
+| `--cpu-quota`                       | `int64`       | `0`       | Limit the CPU CFS (Completely Fair Scheduler) quota               |
+| `-c`, `--cpu-shares`                | `int64`       | `0`       | CPU shares (relative weight)                                      |
+| `--cpuset-cpus`                     | `string`      |           | CPUs in which to allow execution (0-3, 0,1)                       |
+| `--cpuset-mems`                     | `string`      |           | MEMs in which to allow execution (0-3, 0,1)                       |
+| `--disable-content-trust`           |               |           | Skip image verification                                           |
+| [`-f`](#file), [`--file`](#file)    | `string`      |           | Name of the Dockerfile (Default is `PATH/Dockerfile`)             |
+| `--force-rm`                        |               |           | Always remove intermediate containers                             |
+| `--iidfile`                         | `string`      |           | Write the image ID to the file                                    |
+| [`--isolation`](#isolation)         | `string`      |           | Container isolation technology                                    |
+| `--label`                           | `list`        |           | Set metadata for an image                                         |
+| `-m`, `--memory`                    | `bytes`       | `0`       | Memory limit                                                      |
+| `--memory-swap`                     | `bytes`       | `0`       | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
+| `--network`                         | `string`      | `default` | Set the networking mode for the RUN instructions during build     |
+| `--no-cache`                        |               |           | Do not use cache when building the image                          |
+| `--platform`                        | `string`      |           | Set platform if server is multi-platform capable                  |
+| `--pull`                            |               |           | Always attempt to pull a newer version of the image               |
+| `-q`, `--quiet`                     |               |           | Suppress the build output and print image ID on success           |
+| `--rm`                              |               |           | Remove intermediate containers after a successful build           |
+| [`--security-opt`](#security-opt)   | `stringSlice` |           | Security options                                                  |
+| `--shm-size`                        | `bytes`       | `0`       | Size of `/dev/shm`                                                |
+| [`--squash`](#squash)               |               |           | Squash newly built layers into a single new layer                 |
+| [`-t`](#tag), [`--tag`](#tag)       | `list`        |           | Name and optionally a tag in the `name:tag` format                |
+| [`--target`](#target)               | `string`      |           | Set the target build stage to build.                              |
+| [`--ulimit`](#ulimit)               | `ulimit`      |           | Ulimit options                                                    |
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

diff --git a/docs/reference/commandline/builder.md b/docs/reference/commandline/builder.md
@@ -0,0 +1,16 @@
+# builder
+
+<!---MARKER_GEN_START-->
+Manage builds
+
+### Subcommands
+
+| Name                        | Description                      |
+|:----------------------------|:---------------------------------|
+| [`build`](builder_build.md) | Build an image from a Dockerfile |
+| [`prune`](builder_prune.md) | Remove build cache               |
+
+
+
+<!---MARKER_GEN_END-->
+
diff --git a/docs/reference/commandline/builder_build.md b/docs/reference/commandline/builder_build.md
@@ -0,0 +1,50 @@
+# builder build
+
+<!---MARKER_GEN_START-->
+Build an image from a Dockerfile
+
+### Aliases
+
+`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
+
+### Options
+
+| Name                      | Type          | Default   | Description                                                       |
+|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
+| `--add-host`              | `list`        |           | Add a custom host-to-IP mapping (`host:ip`)                       |
+| `--build-arg`             | `list`        |           | Set build-time variables                                          |
+| `--cache-from`            | `stringSlice` |           | Images to consider as cache sources                               |
+| `--cgroup-parent`         | `string`      |           | Optional parent cgroup for the container                          |
+| `--compress`              |               |           | Compress the build context using gzip                             |
+| `--cpu-period`            | `int64`       | `0`       | Limit the CPU CFS (Completely Fair Scheduler) period              |
+| `--cpu-quota`             | `int64`       | `0`       | Limit the CPU CFS (Completely Fair Scheduler) quota               |
+| `-c`, `--cpu-shares`      | `int64`       | `0`       | CPU shares (relative weight)                                      |
+| `--cpuset-cpus`           | `string`      |           | CPUs in which to allow execution (0-3, 0,1)                       |
+| `--cpuset-mems`           | `string`      |           | MEMs in which to allow execution (0-3, 0,1)                       |
+| `--disable-content-trust` |               |           | Skip image verification                                           |
+| `-f`, `--file`            | `string`      |           | Name of the Dockerfile (Default is `PATH/Dockerfile`)             |
+| `--force-rm`              |               |           | Always remove intermediate containers                             |
+| `--iidfile`               | `string`      |           | Write the image ID to the file                                    |
+| `--isolation`             | `string`      |           | Container isolation technology                                    |
+| `--label`                 | `list`        |           | Set metadata for an image                                         |
+| `-m`, `--memory`          | `bytes`       | `0`       | Memory limit                                                      |
+| `--memory-swap`           | `bytes`       | `0`       | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
+| `--network`               | `string`      | `default` | Set the networking mode for the RUN instructions during build     |
+| `--no-cache`              |               |           | Do not use cache when building the image                          |
+| `--platform`              | `string`      |           | Set platform if server is multi-platform capable                  |
+| `--pull`                  |               |           | Always attempt to pull a newer version of the image               |
+| `-q`, `--quiet`           |               |           | Suppress the build output and print image ID on success           |
+| `--rm`                    |               |           | Remove intermediate containers after a successful build           |
+| `--security-opt`          | `stringSlice` |           | Security options                                                  |
+| `--shm-size`              | `bytes`       | `0`       | Size of `/dev/shm`                                                |
+| `--squash`                |               |           | Squash newly built layers into a single new layer                 |
+| `-t`, `--tag`             | `list`        |           | Name and optionally a tag in the `name:tag` format                |
+| `--target`                | `string`      |           | Set the target build stage to build.                              |
+| `--ulimit`                | `ulimit`      |           | Ulimit options                                                    |
+
+
+<!---MARKER_GEN_END-->
+
+## Description
+
+See [docker build](build.md) for more information.
diff --git a/docs/reference/commandline/builder_prune.md b/docs/reference/commandline/builder_prune.md
@@ -0,0 +1,16 @@
+# builder prune
+
+<!---MARKER_GEN_START-->
+Remove build cache
+
+### Options
+
+| Name             | Type     | Default | Description                                           |
+|:-----------------|:---------|:--------|:------------------------------------------------------|
+| `-a`, `--all`    |          |         | Remove all unused build cache, not just dangling ones |
+| `--filter`       | `filter` |         | Provide filter values (e.g. `until=24h`)              |
+| `-f`, `--force`  |          |         | Do not prompt for confirmation                        |
+| `--keep-storage` | `bytes`  | `0`     | Amount of disk space to keep for cache                |
+
+
+<!---MARKER_GEN_END-->
diff --git a/docs/reference/commandline/checkpoint.md b/docs/reference/commandline/checkpoint.md
@@ -1,9 +1,19 @@
----
-title: docker checkpoint
-description: "The checkpoint command description and usage"
-keywords: experimental, checkpoint, restore, criu
-experimental: true
----
+# checkpoint
+
+<!---MARKER_GEN_START-->
+Manage checkpoints
+
+### Subcommands
+
+| Name                             | Description                                  |
+|:---------------------------------|:---------------------------------------------|
+| [`create`](checkpoint_create.md) | Create a checkpoint from a running container |
+| [`ls`](checkpoint_ls.md)         | List checkpoints for a container             |
+| [`rm`](checkpoint_rm.md)         | Remove a checkpoint                          |
+
+
+
+<!---MARKER_GEN_END-->
 
 ## Description
 

diff --git a/docs/reference/commandline/checkpoint_create.md b/docs/reference/commandline/checkpoint_create.md
@@ -0,0 +1,15 @@
+# checkpoint create
+
+<!---MARKER_GEN_START-->
+Create a checkpoint from a running container
+
+### Options
+
+| Name               | Type     | Default | Description                                  |
+|:-------------------|:---------|:--------|:---------------------------------------------|
+| `--checkpoint-dir` | `string` |         | Use a custom checkpoint storage directory    |
+| `--leave-running`  |          |         | Leave the container running after checkpoint |
+
+
+<!---MARKER_GEN_END-->
+
diff --git a/docs/reference/commandline/checkpoint_ls.md b/docs/reference/commandline/checkpoint_ls.md
@@ -0,0 +1,18 @@
+# checkpoint ls
+
+<!---MARKER_GEN_START-->
+List checkpoints for a container
+
+### Aliases
+
+`docker checkpoint ls`, `docker checkpoint list`
+
+### Options
+
+| Name               | Type     | Default | Description                               |
+|:-------------------|:---------|:--------|:------------------------------------------|
+| `--checkpoint-dir` | `string` |         | Use a custom checkpoint storage directory |
+
+
+<!---MARKER_GEN_END-->
+