Skip to content

Commit

Permalink
docs: generate markdown
Browse files Browse the repository at this point in the history 
Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
  • Loading branch information
@crazy-max
crazy-max committed Dec 29, 2022
1 parent 5966bdb commit 7bd4eb2
Show file tree
Hide file tree
Showing 197 changed files with 3,496 additions and 2,831 deletions.
4 changes: 4 additions & 0 deletions Makefile
View file
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions docker.Makefile
View file
Expand Up @@ -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
Expand Down
32 changes: 29 additions & 3 deletions docs/generate.go
View file
Expand Up @@ -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 {
Expand All @@ -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{
Expand All @@ -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)
}

Expand Down
31 changes: 14 additions & 17 deletions docs/reference/commandline/attach.md
View file
@@ -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

Expand Down
99 changes: 42 additions & 57 deletions docs/reference/commandline/build.md
View file
@@ -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` | `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

Expand Down
16 changes: 16 additions & 0 deletions docs/reference/commandline/builder.md
View file
@@ -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-->

50 changes: 50 additions & 0 deletions docs/reference/commandline/builder_build.md
View file
@@ -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.
16 changes: 16 additions & 0 deletions docs/reference/commandline/builder_prune.md
View file
@@ -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-->
22 changes: 16 additions & 6 deletions docs/reference/commandline/checkpoint.md
View file
@@ -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

Expand Down
15 changes: 15 additions & 0 deletions docs/reference/commandline/checkpoint_create.md
View file
@@ -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-->

18 changes: 18 additions & 0 deletions docs/reference/commandline/checkpoint_ls.md
View file
@@ -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-->

0 comments on commit 7bd4eb2

Please sign in to comment.