8000 docs: generate markdown · docker/cli@79c9e52 · GitHub
[go: up one dir, main page]
Skip to content

Commit 79c9e52

Browse files
crazy-maxthaJeztah
crazy-max
authored and
thaJeztah
committed
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>
1 parent 186dcf3 commit 79c9e52

File tree

194 files changed

+3439
-2786
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

194 files changed

+3439
-2786
lines changed

‎Makefile

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,10 @@ authors: ## generate AUTHORS file from git history
9090
manpages: ## generate man pages from go source and markdown
9191
scripts/docs/generate-man.sh
9292

93+
.PHONY: mddocs
94+
mddocs: ## generate markdown files from go source
95+
scripts/docs/generate-md.sh
96+
9397
.PHONY: yamldocs
9498
yamldocs: ## generate documentation YAML files consumed by docs repo
9599
scripts/docs/generate-yaml.sh

‎docker.Makefile

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,10 @@ authors: ## generate AUTHORS file from git history
103103
manpages: build_docker_image ## generate man pages from go source and markdown
104104
$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make manpages
105105

106+
.PHONY: mddocs
107+
mddocs: build_docker_image ## generate markdown files from go source
108+
$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make mddocs
109+
106110
.PHONY: yamldocs
107111
yamldocs: build_docker_image ## generate documentation YAML files consumed by docs repo
108112
$(DOCKER_RUN) -it $(DEV_DOCKER_IMAGE_NAME) make yamldocs

‎docs/generate.go

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,20 @@ import (
1010
"os"
1111

1212
clidocstool "github.com/docker/cli-docs-tool"
13+
"github.com/docker/cli/cli"
1314
"github.com/docker/cli/cli/command"
1415
"github.com/docker/cli/cli/command/commands"
16+
"github.com/pkg/errors"
1517
"github.com/spf13/cobra"
1618
"github.com/spf13/pflag"
1719
)
1820

1921
const defaultSourcePath = "docs/reference/commandline/"
2022

2123
type options struct {
22-
source string
23-
target string
24+
source string
25+
target string
26+
formats []string
2427
}
2528

2629
func gen(opts *options) error {
@@ -34,6 +37,10 @@ func gen(opts *options) error {
3437
Use: "docker [OPTIONS] COMMAND [ARG...]",
3538
Short: "The base command for the Docker CLI.",
3639
}
40+
clientOpts, _, _ := cli.SetupRootCommand(cmd)
41+
if err := dockerCLI.Initialize(clientOpts); err != nil {
42+
return err
43+
}
3744
commands.AddCommands(cmd, dockerCLI)
3845

3946
c, err := clidocstool.New(clidocstool.Options{
@@ -46,17 +53,36 @@ func gen(opts *options) error {
4653
return err
4754
}
4855

49-
return c.GenYamlTree(cmd)
56+
for _, format := range opts.formats {
57+
switch format {
58+
case "md":
59+
if err = c.GenMarkdownTree(cmd); err != nil {
60+
return err
61+
}
62+
case "yaml":
63+
if err = c.GenYamlTree(cmd); err != nil {
64+
return err
65+
}
66+
default:
67+
return errors.Errorf("unknown format %q", format)
68+
}
69+
}
70+
71+
return nil
5072
}
5173

5274
func run() error {
5375
opts := &options{}
5476
flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
5577
flags.StringVar(&opts.source, "source", defaultSourcePath, "Docs source folder")
5678
flags.StringVar(&opts.target, "target", defaultSourcePath, "Docs target folder")
79+
flags.StringSliceVar(&opts.formats, "formats", []string{}, "Format (md, yaml)")
5780
if err := flags.Parse(os.Args[1:]); err != nil {
5881
return err
5982
}
83+
if len(opts.formats) == 0 {
84+
return errors.New("Docs format required")
85+
}
6086
return gen(opts)
6187
}
6288

‎docs/reference/commandline/attach.md

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,22 @@
1-
---
2-
title: "attach"
3-
description: "The attach command description and usage"
4-
keywords: "attach, running, container"
5-
---
6-
71
# attach
82

9-
```markdown
10-
Usage: docker attach [OPTIONS] CONTAINER
11-
3+
<!---MARKER_GEN_START-->
124
Attach local standard input, output, and error streams to a running container
135

14-
Aliases:
15-
docker container attach, docker attach
6+
### Aliases
167

17-
Options:
18-
--detach-keys string Override the key sequence for detaching a container
19-
--help Print usage
20-
--no-stdin Do not attach STDIN
21-
--sig-proxy Proxy all received signals to the process (default true)
22-
```
8+
`docker container attach`, `docker attach`
9+
10+
### Options
11+
12+
| Name | Type | Default | Description |
13+
|:----------------|:---------|:--------|:----------------------------------------------------|
14+
| `--detach-keys` | `string` | | Override the key sequence for detaching a container |
15+
| `--no-stdin` | | | Do not attach STDIN |
16+
| `--sig-proxy` | | | Proxy all received signals to the process |
17+
18+
19+
<!---MARKER_GEN_END-->
2320

2421
## Description
2522

‎docs/reference/commandline/build.md

Lines changed: 42 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,49 @@
1-
---
2-
title: "build"
3-
description: "The build command description and usage"
4-
keywords: "build, docker, image"
5-
---
6-
71
# build
82

9-
```markdown
10-
Usage: docker build [OPTIONS] PATH | URL | -
11-
3+
<!---MARKER_GEN_START-->
124
Build an image from a Dockerfile
135

14-
Aliases:
15-
docker image build, docker build, docker buildx build, docker builder build
16-
17-
Options:
18-
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
19-
--build-arg value Set build-time variables (default [])
20-
--cache-from value Images to consider as cache sources (default [])
21-
--cgroup-parent string Optional parent cgroup for the container
22-
--compress Compress the build context using gzip
23-
--cpu-period int Limit the CPU CFS (Completely Fair Scheduler) period
24-
--cpu-quota int Limit the CPU CFS (Completely Fair Scheduler) quota
25-
-c, --cpu-shares int CPU shares (relative weight)
26-
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
27-
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
28-
--disable-content-trust Skip image verification (default true)
29-
-f, --file string Name of the Dockerfile (Default is 'PATH/Dockerfile')
30-
--force-rm Always remove intermediate containers
31-
--help Print usage
32-
--iidfile string Write the image ID to the file
33-
--isolation string Container isolation technology
34-
--label value Set metadata for an image (default [])
35-
-m, --memory string Memory limit
36-
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
37-
--network string Set the networking mode for the RUN instructions during build
38-
'bridge': use default Docker bridge
39-
'none': no networking
40-
'container:<name|id>': reuse another container's network stack
41-
'host': use the Docker host network stack
42-
'<network-name>|<network-id>': connect to a user-defined network
43-
--no-cache Do not use cache when building the image
44-
-o, --output Output destination (format: type=local,dest=path)
45-
--pull Always attempt to pull a newer version of the image
46-
--progress Set type of progress output (only if BuildKit enabled) (auto, plain, tty).
47-
Use plain to show container output
48-
-q, --quiet Suppress the build output and print image ID on success
49-
--rm Remove intermediate containers after a successful build (default true)
50-
--secret Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret"
51-
--security-opt value Security Options (default [])
52-
--shm-size bytes Size of /dev/shm
53-
The format is `<number><unit>`. `number` must be greater than `0`.
54-
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
55-
or `g` (gigabytes). If you omit the unit, the system uses bytes.
56-
--squash Squash newly built layers into a single new layer (**Experimental Only**)
57-
--ssh SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])
58-
-t, --tag value Name and optionally a tag in the 'name:tag' format (default [])
59-
--target string Set the target build stage to build.
60-
--ulimit value Ulimit options (default [])
61-
```
6+
### Aliases
7+
8+
`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
9+
10+
### Options
11+
12+
| Name | Type | Default | Description |
13+
|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------|
14+
| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
15+
| [`--build-arg`](#build-arg) | `list` | | Set build-time variables |
16+
| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources |
17+
| [`--cgroup-parent`](#cgroup-parent) | `string` | | Optional parent cgroup for the container |
18+
| `--compress` | | | Compress the build context using gzip |
19+
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
20+
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
21+
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
22+
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
23+
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
24+
| `--disable-content-trust` | | | Skip image verification |
25+
| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
26+
| `--force-rm` | | | Always remove intermediate containers |
27+
| `--iidfile` | `string` | | Write the image ID to the file |
28+
| [`--isolation`](#isolation) | `string` | | Container isolation technology |
29+
| `--label` | `list` | | Set metadata for an image |
30+
| `-m`, `--memory` | `bytes` | `0` | Memory limit |
31+
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
32+
| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
33+
| `--no-cache` | | | Do not use cache when building the image |
34+
| `--platform` | `string` | | Set platform if server is multi-platform capable |
35+
| `--pull` | | | Always attempt to pull a newer version of the image |
36+
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
37+
| `--rm` | | | Remove intermediate containers after a successful build |
38+
| [`--security-opt`](#security-opt) | `stringSlice` | | Security options |
39+
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
40+
| [`--squash`](#squash) | | | Squash newly built layers into a single new layer |
41+
| [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format |
42+
| [`--target`](#target) | `string` | | Set the target build stage to build. |
43+
| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options |
44+
45+
46+
<!---MARKER_GEN_END-->
6247

6348
## Description
6449

‎docs/reference/commandline/builder.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# builder
2+
3+
<!---MARKER_GEN_START-->
4+
Manage builds
5+
6+
### Subcommands
7+
8+
| Name | Description |
9+
|:----------------------------|:---------------------------------|
10+
| [`build`](builder_build.md) | Build an image from a Dockerfile |
11+
| [`prune`](builder_prune.md) | Remove build cache |
12+
13+
14+
15+
<!---MARKER_GEN_END-->
16+

‎docs/reference/commandline/builder_build.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# builder build
2+
3+
<!---MARKER_GEN_START-->
4+
Build an image from a Dockerfile
5+
6+
### Aliases
7+
8+
`docker image build`, `docker build`, `docker buildx build`, `docker builder build`
9+
10+
### Options
11+
12+
| Name | Type | Default | Description |
13+
|:--------------------------|:--------------|:----------|:------------------------------------------------------------------|
14+
| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) |
15+
| `--build-arg` | `list` | | Set build-time variables |
16+
| `--cache-from` | `stringSlice` | | Images to consider as cache sources |
17+
| `--cgroup-parent` | `string` | | Optional parent cgroup for the container |
18+
| `--compress` | | | Compress the build context using gzip |
19+
| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period |
20+
| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota |
21+
| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) |
22+
| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) |
23+
| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) |
24+
| `--disable-content-trust` | | | Skip image verification |
25+
| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) |
26+
| `--force-rm` | | | Always remove intermediate containers |
27+
| `--iidfile` | `string` | | Write the image ID to the file |
28+
| `--isolation` | `string` | | Container isolation technology |
29+
| `--label` | `list` | | Set metadata for an image |
30+
| `-m`, `--memory` | `bytes` | `0` | Memory limit |
31+
| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap |
32+
| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build |
33+
| `--no-cache` | | | Do not use cache when building the image |
34+
| `--platform` | `string` | | Set platform if server is multi-platform capable |
35+
| `--pull` | | | Always attempt to pull a newer version of the image |
36+
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
37+
| `--rm` | | | Remove intermediate containers after a successful build |
38+
| `--security-opt` | `stringSlice` | | Security options |
39+
| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` |
40+
| `--squash` | | | Squash newly built layers into a single new layer |
41+
| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format |
42+
| `--target` | `string` | | Set the target build stage to build. |
43+
| `--ulimit` | `ulimit` | | Ulimit options |
44+
45+
46+
<!---MARKER_GEN_END-->
47+
48+
## Description
49+
50+
See [docker build](build.md) for more information.

‎docs/reference/commandline/builder_prune.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# builder prune
2+
3+
<!---MARKER_GEN_START-->
4+
Remove build cache
5+
6+
### Options
7+
8+
| Name | Type | Default | Description |
9+
|:-----------------|:---------|:--------|:------------------------------------------------------|
10+
| `-a`, `--all` | | | Remove all unused build cache, not just dangling ones |
11+
| `--filter` | `filter` | | Provide filter values (e.g. `until=24h`) |
12+
| `-f`, `--force` | | | Do not prompt for confirmation |
13+
| `--keep-storage` | `bytes` | `0` | Amount of disk space to keep for cache |
14+
15+
16+
<!---MARKER_GEN_END-->

‎docs/reference/commandline/checkpoint.md

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
1-
---
2-
title: docker checkpoint
3-
description: "The checkpoint command description and usage"
4-
keywords: experimental, checkpoint, restore, criu
5-
experimental: true
6-
---
1+
# checkpoint
2+
3+
<!---MARKER_GEN_START-->
4+
Manage checkpoints
5+
6+
### Subcommands
7+
8+
| Name | Description |
9+
|:---------------------------------|:---------------------------------------------|
10+
| [`create`](checkpoint_create.md) | Create a checkpoint from a running container |
11+
| [`ls`](checkpoint_ls.md) | List checkpoints for a container |
12+
| [`rm`](checkpoint_rm.md) | Remove a checkpoint |
13+
14+
15+
16+
<!---MARKER_GEN_END-->
717

818
## Description
919

‎docs/reference/commandline/checkpoint_create.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# checkpoint create
2+
3+
<!---MARKER_GEN_START-->
4+
Create a checkpoint from a running container
5+
6+
### Options
7+
8+
| Name | Type | Default | Description |
9+
|:-------------------|:---------|:--------|:---------------------------------------------|
10+
| `--checkpoint-dir` | `string` | | Use a custom checkpoint storage directory |
11+
| `--leave-running` | | | Leave the container running after checkpoint |
12+
13+
14+
<!---MARKER_GEN_END-->
15+

0 commit comments

Comments
 (0)
0