tyler.durden
/
compose
mirror of https://github.com/docker/compose.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

generate reference documentation 

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Nicolas De Loof 2021-03-08 15:47:24 +01:00
parent 4a8a1aeb48
commit 59d4382f3c
No known key found for this signature in database
GPG Key ID: 9858809D6F8F6E7E
45 changed files with 1502 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
builder.Makefile
View File

@ -95,3 +95,7 @@ package: cross
cp $(BINARY)-windows-amd64.exe $(WORK_DIR)/docker.exe
rm -f dist/docker-windows-amd64.zip && zip dist/docker-windows-amd64.zip -j packaging/LICENSE $(WORK_DIR)/docker.exe
rm -r $(WORK_DIR)
.PHONY: yamldocs
yamldocs:
go run docs/yaml/main/generate.go

0
docs/reference/compose.md Normal file
View File

0
docs/reference/compose_build.md Normal file
View File

0
docs/reference/compose_convert.md Normal file
View File

0
docs/reference/compose_create.md Normal file
View File

0
docs/reference/compose_down.md Normal file
View File

0
docs/reference/compose_events.md Normal file
View File

0
docs/reference/compose_exec.md Normal file
View File

0
docs/reference/compose_kill.md Normal file
View File

0
docs/reference/compose_logs.md Normal file
View File

0
docs/reference/compose_ls.md Normal file
View File

0
docs/reference/compose_pause.md Normal file
View File

0
docs/reference/compose_ps.md Normal file
View File

0
docs/reference/compose_pull.md Normal file
View File

0
docs/reference/compose_push.md Normal file
View File

0
docs/reference/compose_rm.md Normal file
View File

0
docs/reference/compose_run.md Normal file
View File

0
docs/reference/compose_start.md Normal file
View File

0
docs/reference/compose_stop.md Normal file
View File

0
docs/reference/compose_top.md Normal file
View File

0
docs/reference/compose_unpause.md Normal file
View File

0
docs/reference/compose_up.md Normal file
View File

121
docs/reference/docker_compose.yaml Normal file
View File

@ -0,0 +1,121 @@
command: docker compose
short: Docker Compose
long: Docker Compose
pname: docker
plink: docker.yaml
cname:
- docker compose build
- docker compose convert
- docker compose create
- docker compose down
- docker compose events
- docker compose exec
- docker compose kill
- docker compose logs
- docker compose ls
- docker compose pause
- docker compose ps
- docker compose pull
- docker compose push
- docker compose rm
- docker compose run
- docker compose start
- docker compose stop
- docker compose top
- docker compose unpause
- docker compose up
clink:
- docker_compose_build.yaml
- docker_compose_convert.yaml
- docker_compose_create.yaml
- docker_compose_down.yaml
- docker_compose_events.yaml
- docker_compose_exec.yaml
- docker_compose_kill.yaml
- docker_compose_logs.yaml
- docker_compose_ls.yaml
- docker_compose_pause.yaml
- docker_compose_ps.yaml
- docker_compose_pull.yaml
- docker_compose_push.yaml
- docker_compose_rm.yaml
- docker_compose_run.yaml
- docker_compose_start.yaml
- docker_compose_stop.yaml
- docker_compose_top.yaml
- docker_compose_unpause.yaml
- docker_compose_up.yaml
options:
- option: ansi
value_type: string
default_value: auto
description: |
Control when to print ANSI control characters ("never"|"always"|"auto")
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: env-file
value_type: string
description: Specify an alternate environment file.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: file
shorthand: f
value_type: stringArray
default_value: '[]'
description: Compose configuration files
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: profile
value_type: stringArray
default_value: '[]'
description: Specify a profile to enable
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: project-directory
value_type: string
description: |-
Specify an alternate working directory
(default: the path of the Compose file)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: project-name
shorthand: p
value_type: string
description: Project name
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: workdir
value_type: string
description: |-
DEPRECATED! USE --project-directory INSTEAD.
Specify an alternate working directory
(default: the path of the Compose file)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

50
docs/reference/docker_compose_build.yaml Normal file
View File

@ -0,0 +1,50 @@
command: docker compose build
short: Build or rebuild services
long: Build or rebuild services
usage: docker compose build [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: build-arg
value_type: stringArray
default_value: '[]'
description: Set build-time variables for services.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: progress
value_type: string
default_value: auto
description: Set type of progress output ("auto", "plain", "tty")
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: pull
value_type: bool
default_value: "false"
description: Always attempt to pull a newer version of the image.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Don't print anything to STDOUT
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

42
docs/reference/docker_compose_convert.yaml Normal file
View File

@ -0,0 +1,42 @@
command: docker compose convert
aliases: config
short: Converts the compose file to platform's canonical format
long: Converts the compose file to platform's canonical format
usage: docker compose convert SERVICES
pname: docker compose
plink: docker_compose.yaml
options:
- option: format
value_type: string
default_value: yaml
description: 'Format the output. Values: [yaml | json]'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Only validate the configuration, don't print anything.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: resolve-image-digests
value_type: bool
default_value: "false"
description: Pin image tags to digests.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

51
docs/reference/docker_compose_create.yaml Normal file
View File

@ -0,0 +1,51 @@
command: docker compose create
short: Creates containers for a service.
long: Creates containers for a service.
usage: docker compose create [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: build
value_type: bool
default_value: "false"
description: Build images before starting containers.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: force-recreate
value_type: bool
default_value: "false"
description: |
Recreate containers even if their configuration and image haven't changed.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-build
value_type: bool
default_value: "false"
description: Don't build an image, even if it's missing.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-recreate
value_type: bool
default_value: "false"
description: |
If containers already exist, don't recreate them. Incompatible with --force-recreate.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

53
docs/reference/docker_compose_down.yaml Normal file
View File

@ -0,0 +1,53 @@
command: docker compose down
short: Stop and remove containers, networks
long: Stop and remove containers, networks
usage: docker compose down
pname: docker compose
plink: docker_compose.yaml
options:
- option: remove-orphans
value_type: bool
default_value: "false"
description: |
Remove containers for services not defined in the Compose file.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: rmi
value_type: string
description: |
Remove images used by services. "local" remove only images that don't have a custom tag ("local"|"all")
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: timeout
shorthand: t
value_type: int
default_value: "10"
description: Specify a shutdown timeout in seconds
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: volumes
shorthand: v
value_type: bool
default_value: "false"
description: |4
Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

22
docs/reference/docker_compose_events.yaml Normal file
View File

@ -0,0 +1,22 @@
command: docker compose events
short: Receive real time events from containers.
long: Receive real time events from containers.
usage: docker compose events [options] [--] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: json
value_type: bool
default_value: "false"
description: Output events as a stream of json objects
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

81
docs/reference/docker_compose_exec.yaml Normal file
View File

@ -0,0 +1,81 @@
command: docker compose exec
short: Execute a command in a running container.
long: Execute a command in a running container.
usage: docker compose exec [options] [-e KEY=VAL...] [--] SERVICE COMMAND [ARGS...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: ""
shorthand: T
value_type: bool
default_value: "false"
description: |
Disable pseudo-tty allocation. By default `docker compose exec` allocates a TTY.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: detach
shorthand: d
value_type: bool
default_value: "false"
description: 'Detached mode: Run command in the background.'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: env
shorthand: e
value_type: stringArray
default_value: '[]'
description: Set environment variables
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: index
value_type: int
default_value: "1"
description: |
index of the container if there are multiple instances of a service [default: 1].
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: privileged
value_type: bool
default_value: "false"
description: Give extended privileges to the process.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: user
shorthand: u
value_type: string
description: Run the command as this user.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: workdir
shorthand: w
value_type: string
description: Path to workdir directory for this command.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

23
docs/reference/docker_compose_kill.yaml Normal file
View File

@ -0,0 +1,23 @@
command: docker compose kill
short: Force stop service containers.
long: Force stop service containers.
usage: docker compose kill [options] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: signal
shorthand: s
value_type: string
default_value: SIGKILL
description: SIGNAL to send to the container.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

51
docs/reference/docker_compose_logs.yaml Normal file
View File

@ -0,0 +1,51 @@
command: docker compose logs
short: View output from containers
long: View output from containers
usage: docker compose logs [service...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: follow
shorthand: f
value_type: bool
default_value: "false"
description: Follow log output.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-color
value_type: bool
default_value: "false"
description: Produce monochrome output.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-log-prefix
value_type: bool
default_value: "false"
description: Don't print prefix in logs.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: timestamps
shorthand: t
value_type: bool
default_value: "false"
description: Show timestamps.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

40
docs/reference/docker_compose_ls.yaml Normal file
View File

@ -0,0 +1,40 @@
command: docker compose ls
short: List running compose projects
long: List running compose projects
usage: docker compose ls
pname: docker compose
plink: docker_compose.yaml
options:
- option: filter
value_type: filter
description: Filter output based on conditions provided.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
default_value: pretty
description: 'Format the output. Values: [pretty | json].'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Only display IDs.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

12
docs/reference/docker_compose_pause.yaml Normal file
View File

@ -0,0 +1,12 @@
command: docker compose pause
short: pause services
long: pause services
usage: docker compose pause [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

52
docs/reference/docker_compose_ps.yaml Normal file
View File

@ -0,0 +1,52 @@
command: docker compose ps
short: List containers
long: List containers
usage: docker compose ps
pname: docker compose
plink: docker_compose.yaml
options:
- option: all
shorthand: a
value_type: bool
default_value: "false"
description: |
Show all stopped containers (including those created by the run command)
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
default_value: pretty
description: 'Format the output. Values: [pretty | json].'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Only display IDs
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: services
value_type: bool
default_value: "false"
description: Display services
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

32
docs/reference/docker_compose_pull.yaml Normal file
View File

@ -0,0 +1,32 @@
command: docker compose pull
short: Pull service images
long: Pull service images
usage: docker compose pull [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: include-deps
value_type: bool
default_value: "false"
description: Also pull services declared as dependencies
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: quiet
shorthand: q
value_type: bool
default_value: "false"
description: Pull without printing progress information
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

22
docs/reference/docker_compose_push.yaml Normal file
View File

@ -0,0 +1,22 @@
command: docker compose push
short: Push service images
long: Push service images
usage: docker compose push [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: ignore-push-failures
value_type: bool
default_value: "false"
description: Push what it can and ignores images with push failures
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

43
docs/reference/docker_compose_rm.yaml Normal file
View File

@ -0,0 +1,43 @@
command: docker compose rm
short: Removes stopped service containers
long: Removes stopped service containers
usage: docker compose rm [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: force
shorthand: f
value_type: bool
default_value: "false"
description: Don't ask to confirm removal
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: stop
shorthand: s
value_type: bool
default_value: "false"
description: Stop the containers, if required, before removing
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: volumes
shorthand: v
value_type: bool
default_value: "false"
description: Remove any anonymous volumes attached to containers
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

147
docs/reference/docker_compose_run.yaml Normal file
View File

@ -0,0 +1,147 @@
command: docker compose run
short: Run a one-off command on a service.
long: Run a one-off command on a service.
usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l
KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: detach
shorthand: d
value_type: bool
default_value: "false"
description: Run container in background and print container ID
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: entrypoint
value_type: string
description: Override the entrypoint of the image
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: env
shorthand: e
value_type: stringArray
default_value: '[]'
description: Set environment variables
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: labels
shorthand: l
value_type: stringArray
default_value: '[]'
description: Add or override a label
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: name
value_type: string
description: ' Assign a name to the container'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-TTY
shorthand: T
value_type: bool
default_value: "false"
description: |
Disable pseudo-tty allocation. By default docker compose run allocates a TTY
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-deps
value_type: bool
default_value: "false"
description: Don't start linked services.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: publish
shorthand: p
value_type: stringArray
default_value: '[]'
description: Publish a container's port(s) to the host.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: rm
value_type: bool
default_value: "false"
description: Automatically remove the container when it exits
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: service-ports
value_type: bool
default_value: "false"
description: |
Run command with the service's ports enabled and mapped to the host.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: use-aliases
value_type: bool
default_value: "false"
description: |
Use the service's network useAliases in the network(s) the container connects to.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: user
shorthand: u
value_type: string
description: Run as specified username or uid
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: volumes
shorthand: v
value_type: stringArray
default_value: '[]'
description: Bind mount a volume.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: workdir
shorthand: w
value_type: string
description: Working directory inside the container
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

12
docs/reference/docker_compose_start.yaml Normal file
View File

@ -0,0 +1,12 @@
command: docker compose start
short: Start services
long: Start services
usage: docker compose start [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

23
docs/reference/docker_compose_stop.yaml Normal file
View File

@ -0,0 +1,23 @@
command: docker compose stop
short: Stop services
long: Stop services
usage: docker compose stop [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: timeout
shorthand: t
value_type: int
default_value: "10"
description: Specify a shutdown timeout in seconds
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

12
docs/reference/docker_compose_top.yaml Normal file
View File

@ -0,0 +1,12 @@
command: docker compose top
short: Display the running processes
long: Display the running processes
usage: docker compose top
pname: docker compose
plink: docker_compose.yaml
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

12
docs/reference/docker_compose_unpause.yaml Normal file
View File

@ -0,0 +1,12 @@
command: docker compose unpause
short: unpause services
long: unpause services
usage: docker compose unpause [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

187
docs/reference/docker_compose_up.yaml Normal file
View File

@ -0,0 +1,187 @@
command: docker compose up
short: Create and start containers
long: Create and start containers
usage: docker compose up [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: abort-on-container-exit
value_type: bool
default_value: "false"
description: |
Stops all containers if any container was stopped. Incompatible with -d
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: always-recreate-deps
value_type: bool
default_value: "false"
description: |
Recreate dependent containers. Incompatible with --no-recreate.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: attach-dependencies
value_type: bool
default_value: "false"
description: Attach to dependent containers.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: build
value_type: bool
default_value: "false"
description: Build images before starting containers.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: detach
shorthand: d
value_type: bool
default_value: "false"
description: 'Detached mode: Run containers in the background'
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: environment
shorthand: e
value_type: stringArray
default_value: '[]'
description: Environment variables
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: exit-code-from
value_type: string
description: |
Return the exit code of the selected service container. Implies --abort-on-container-exit
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: force-recreate
value_type: bool
default_value: "false"
description: |
Recreate containers even if their configuration and image haven't changed.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-build
value_type: bool
default_value: "false"
description: Don't build an image, even if it's missing.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-color
value_type: bool
default_value: "false"
description: Produce monochrome output.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-deps
value_type: bool
default_value: "false"
description: Don't start linked services.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-log-prefix
value_type: bool
default_value: "false"
description: Don't print prefix in logs.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-recreate
value_type: bool
default_value: "false"
description: |
If containers already exist, don't recreate them. Incompatible with --force-recreate.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-start
value_type: bool
default_value: "false"
description: Don't start the services after creating them.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: remove-orphans
value_type: bool
default_value: "false"
description: |
Remove containers for services not defined in the Compose file.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: renew-anon-volumes
shorthand: V
value_type: bool
default_value: "false"
description: |
Recreate anonymous volumes instead of retrieving data from the previous containers.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: scale
value_type: stringArray
default_value: '[]'
description: |
Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: timeout
shorthand: t
value_type: int
default_value: "10"
description: |
Use this timeout in seconds for container shutdown when attached or when containers are already running.
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false

120
docs/yaml/main/generate.go Normal file
View File

@ -0,0 +1,120 @@
/*
Copyright 2020 Docker Compose CLI authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package main
import (
"fmt"
"io/ioutil"
"log"
"os"
"path/filepath"
"strings"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
"github.com/docker/compose-cli/cli/cmd/compose"
. "github.com/docker/compose-cli/docs/yaml"
)
const descriptionSourcePath = "docs/reference/"
func generateCliYaml(opts *options) error {
cmd := &cobra.Command{Use: "docker"}
cmd.AddCommand(compose.Command("local"))
disableFlagsInUseLine(cmd)
source := filepath.Join(opts.source, descriptionSourcePath)
if err := loadLongDescription(cmd, source); err != nil {
return err
}
cmd.DisableAutoGenTag = true
return GenYamlTree(cmd, opts.target)
}
func disableFlagsInUseLine(cmd *cobra.Command) {
visitAll(cmd, func(ccmd *cobra.Command) {
// do not add a `[flags]` to the end of the usage line.
ccmd.DisableFlagsInUseLine = true
})
}
// visitAll will traverse all commands from the root.
// This is different from the VisitAll of cobra.Command where only parents
// are checked.
func visitAll(root *cobra.Command, fn func(*cobra.Command)) {
for _, cmd := range root.Commands() {
visitAll(cmd, fn)
}
fn(root)
}
func loadLongDescription(cmd *cobra.Command, path ...string) error {
for _, cmd := range cmd.Commands() {
if cmd.Name() == "" {
continue
}
fullpath := filepath.Join(path[0], strings.Join(append(path[1:], cmd.Name()), "_")+".md")
if cmd.HasSubCommands() {
if err := loadLongDescription(cmd, path[0], cmd.Name()); err != nil {
return err
}
}
if _, err := os.Stat(fullpath); err != nil {
log.Printf("WARN: %s does not exist, skipping\n", fullpath)
continue
}
content, err := ioutil.ReadFile(fullpath)
if err != nil {
return err
}
description, examples := ParseMDContent(string(content))
cmd.Long = description
cmd.Example = examples
}
return nil
}
type options struct {
source string
target string
}
func parseArgs() (*options, error) {
opts := &options{}
cwd, _ := os.Getwd()
flags := pflag.NewFlagSet(os.Args[0], pflag.ContinueOnError)
flags.StringVar(&opts.source, "root", cwd, "Path to project root")
flags.StringVar(&opts.target, "target", filepath.Join(cwd, "docs", "reference"), "Target path for generated yaml files")
err := flags.Parse(os.Args[1:])
return opts, err
}
func main() {
opts, err := parseArgs()
if err != nil {
fmt.Fprintln(os.Stderr, err.Error())
}
fmt.Printf("Project root: %s\n", opts.source)
fmt.Printf("Generating yaml files into %s\n", opts.target)
if err := generateCliYaml(opts); err != nil {
fmt.Fprintf(os.Stderr, "Failed to generate yaml files: %s\n", err.Error())
}
}

290
docs/yaml/yaml.go Normal file
View File

@ -0,0 +1,290 @@
/*
Copyright 2020 Docker Compose CLI authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package yaml
import (
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/spf13/pflag"
yaml "gopkg.in/yaml.v3"
)
type cmdOption struct {
Option string
Shorthand string `yaml:",omitempty"`
ValueType string `yaml:"value_type,omitempty"`
DefaultValue string `yaml:"default_value,omitempty"`
Description string `yaml:",omitempty"`
Deprecated bool
MinAPIVersion string `yaml:"min_api_version,omitempty"`
Experimental bool
ExperimentalCLI bool
Kubernetes bool
Swarm bool
OSType string `yaml:"os_type,omitempty"`
}
type cmdDoc struct {
Name string `yaml:"command"`
SeeAlso []string `yaml:"parent,omitempty"`
Version string `yaml:"engine_version,omitempty"`
Aliases string `yaml:",omitempty"`
Short string `yaml:",omitempty"`
Long string `yaml:",omitempty"`
Usage string `yaml:",omitempty"`
Pname string `yaml:",omitempty"`
Plink string `yaml:",omitempty"`
Cname []string `yaml:",omitempty"`
Clink []string `yaml:",omitempty"`
Options []cmdOption `yaml:",omitempty"`
InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
Example string `yaml:"examples,omitempty"`
Deprecated bool
MinAPIVersion string `yaml:"min_api_version,omitempty"`
Experimental bool
ExperimentalCLI bool
Kubernetes bool
Swarm bool
OSType string `yaml:"os_type,omitempty"`
}
// GenYamlTree creates yaml structured ref files
func GenYamlTree(cmd *cobra.Command, dir string) error {
emptyStr := func(s string) string { return "" }
return GenYamlTreeCustom(cmd, dir, emptyStr)
}
// GenYamlTreeCustom creates yaml structured ref files
func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string) error {
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
continue
}
if err := GenYamlTreeCustom(c, dir, filePrepender); err != nil {
return err
}
}
if !cmd.HasParent() {
return nil
}
basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
filename := filepath.Join(dir, basename)
f, err := os.Create(filename)
if err != nil {
return err
}
defer f.Close() //nolint: errcheck
if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
return err
}
return GenYamlCustom(cmd, f)
}
// GenYamlCustom creates custom yaml output
// nolint: gocyclo
func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
cliDoc := cmdDoc{}
cliDoc.Name = cmd.CommandPath()
cliDoc.Aliases = strings.Join(cmd.Aliases, ", ")
cliDoc.Short = cmd.Short
cliDoc.Long = cmd.Long
if len(cliDoc.Long) == 0 {
cliDoc.Long = cliDoc.Short
}
if cmd.Runnable() {
cliDoc.Usage = cmd.UseLine()
}
if len(cmd.Example) > 0 {
cliDoc.Example = cmd.Example
}
if len(cmd.Deprecated) > 0 {
cliDoc.Deprecated = true
}
// Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack`
for curr := cmd; curr != nil; curr = curr.Parent() {
if v, ok := curr.Annotations["version"]; ok && cliDoc.MinAPIVersion == "" {
cliDoc.MinAPIVersion = v
}
if _, ok := curr.Annotations["experimental"]; ok && !cliDoc.Experimental {
cliDoc.Experimental = true
}
if _, ok := curr.Annotations["experimentalCLI"]; ok && !cliDoc.ExperimentalCLI {
cliDoc.ExperimentalCLI = true
}
if _, ok := curr.Annotations["kubernetes"]; ok && !cliDoc.Kubernetes {
cliDoc.Kubernetes = true
}
if _, ok := curr.Annotations["swarm"]; ok && !cliDoc.Swarm {
cliDoc.Swarm = true
}
if os, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" {
cliDoc.OSType = os
}
}
flags := cmd.NonInheritedFlags()
if flags.HasFlags() {
cliDoc.Options = genFlagResult(flags)
}
flags = cmd.InheritedFlags()
if flags.HasFlags() {
cliDoc.InheritedOptions = genFlagResult(flags)
}
if hasSeeAlso(cmd) {
if cmd.HasParent() {
parent := cmd.Parent()
cliDoc.Pname = parent.CommandPath()
link := cliDoc.Pname + ".yaml"
cliDoc.Plink = strings.Replace(link, " ", "_", -1)
cmd.VisitParents(func(c *cobra.Command) {
if c.DisableAutoGenTag {
cmd.DisableAutoGenTag = c.DisableAutoGenTag
}
})
}
children := cmd.Commands()
sort.Sort(byName(children))
for _, child := range children {
if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
continue
}
currentChild := cliDoc.Name + " " + child.Name()
cliDoc.Cname = append(cliDoc.Cname, cliDoc.Name+" "+child.Name())
link := currentChild + ".yaml"
cliDoc.Clink = append(cliDoc.Clink, strings.Replace(link, " ", "_", -1))
}
}
final, err := yaml.Marshal(&cliDoc)
if err != nil {
fmt.Println(err)
os.Exit(1)
}
if _, err := fmt.Fprintln(w, string(final)); err != nil {
return err
}
return nil
}
func genFlagResult(flags *pflag.FlagSet) []cmdOption {
var (
result []cmdOption
opt cmdOption
)
flags.VisitAll(func(flag *pflag.Flag) {
opt = cmdOption{
Option: flag.Name,
ValueType: flag.Value.Type(),
DefaultValue: forceMultiLine(flag.DefValue),
Description: forceMultiLine(flag.Usage),
Deprecated: len(flag.Deprecated) > 0,
}
// Todo, when we mark a shorthand is deprecated, but specify an empty message.
// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
opt.Shorthand = flag.Shorthand
}
if _, ok := flag.Annotations["experimental"]; ok {
opt.Experimental = true
}
if v, ok := flag.Annotations["version"]; ok {
opt.MinAPIVersion = v[0]
}
if _, ok := flag.Annotations["experimentalCLI"]; ok {
opt.ExperimentalCLI = true
}
if _, ok := flag.Annotations["kubernetes"]; ok {
opt.Kubernetes = true
}
if _, ok := flag.Annotations["swarm"]; ok {
opt.Swarm = true
}
// Note that the annotation can have multiple ostypes set, however, multiple
// values are currently not used (and unlikely will).
//
// To simplify usage of the os_type property in the YAML, and for consistency
// with the same property for commands, we're only using the first ostype that's set.
if ostypes, ok := flag.Annotations["ostype"]; ok && len(opt.OSType) == 0 && len(ostypes) > 0 {
opt.OSType = ostypes[0]
}
result = append(result, opt)
})
return result
}
// Temporary workaround for yaml lib generating incorrect yaml with long strings
// that do not contain \n.
func forceMultiLine(s string) string {
if len(s) > 60 && !strings.Contains(s, "\n") {
s = s + "\n"
}
return s
}
// Small duplication for cobra utils
func hasSeeAlso(cmd *cobra.Command) bool {
if cmd.HasParent() {
return true
}
for _, c := range cmd.Commands() {
if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
continue
}
return true
}
return false
}
// ParseMDContent parse markdown file looking for Description and Examples sections
func ParseMDContent(mdString string) (description string, examples string) {
parsedContent := strings.Split(mdString, "\n## ")
for _, s := range parsedContent {
if strings.Index(s, "Description") == 0 {
description = strings.TrimSpace(strings.TrimPrefix(s, "Description"))
}
if strings.Index(s, "Examples") == 0 {
examples = strings.TrimSpace(strings.TrimPrefix(s, "Examples"))
}
}
return description, examples
}
type byName []*cobra.Command
func (s byName) Len() int { return len(s) }
func (s byName) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }