From 59d4382f3c0a47b295fdcb23d25c5515790ebf13 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Mon, 8 Mar 2021 15:47:24 +0100 Subject: [PATCH] generate reference documentation Signed-off-by: Nicolas De Loof --- builder.Makefile | 4 + docs/reference/compose.md | 0 docs/reference/compose_build.md | 0 docs/reference/compose_convert.md | 0 docs/reference/compose_create.md | 0 docs/reference/compose_down.md | 0 docs/reference/compose_events.md | 0 docs/reference/compose_exec.md | 0 docs/reference/compose_kill.md | 0 docs/reference/compose_logs.md | 0 docs/reference/compose_ls.md | 0 docs/reference/compose_pause.md | 0 docs/reference/compose_ps.md | 0 docs/reference/compose_pull.md | 0 docs/reference/compose_push.md | 0 docs/reference/compose_rm.md | 0 docs/reference/compose_run.md | 0 docs/reference/compose_start.md | 0 docs/reference/compose_stop.md | 0 docs/reference/compose_top.md | 0 docs/reference/compose_unpause.md | 0 docs/reference/compose_up.md | 0 docs/reference/docker_compose.yaml | 121 +++++++++ docs/reference/docker_compose_build.yaml | 50 ++++ docs/reference/docker_compose_convert.yaml | 42 +++ docs/reference/docker_compose_create.yaml | 51 ++++ docs/reference/docker_compose_down.yaml | 53 ++++ docs/reference/docker_compose_events.yaml | 22 ++ docs/reference/docker_compose_exec.yaml | 81 ++++++ docs/reference/docker_compose_kill.yaml | 23 ++ docs/reference/docker_compose_logs.yaml | 51 ++++ docs/reference/docker_compose_ls.yaml | 40 +++ docs/reference/docker_compose_pause.yaml | 12 + docs/reference/docker_compose_ps.yaml | 52 ++++ docs/reference/docker_compose_pull.yaml | 32 +++ docs/reference/docker_compose_push.yaml | 22 ++ docs/reference/docker_compose_rm.yaml | 43 +++ docs/reference/docker_compose_run.yaml | 147 +++++++++++ docs/reference/docker_compose_start.yaml | 12 + docs/reference/docker_compose_stop.yaml | 23 ++ docs/reference/docker_compose_top.yaml | 12 + docs/reference/docker_compose_unpause.yaml | 12 + docs/reference/docker_compose_up.yaml | 187 +++++++++++++ docs/yaml/main/generate.go | 120 +++++++++ docs/yaml/yaml.go | 290 +++++++++++++++++++++ 45 files changed, 1502 insertions(+) create mode 100644 docs/reference/compose.md create mode 100644 docs/reference/compose_build.md create mode 100644 docs/reference/compose_convert.md create mode 100644 docs/reference/compose_create.md create mode 100644 docs/reference/compose_down.md create mode 100644 docs/reference/compose_events.md create mode 100644 docs/reference/compose_exec.md create mode 100644 docs/reference/compose_kill.md create mode 100644 docs/reference/compose_logs.md create mode 100644 docs/reference/compose_ls.md create mode 100644 docs/reference/compose_pause.md create mode 100644 docs/reference/compose_ps.md create mode 100644 docs/reference/compose_pull.md create mode 100644 docs/reference/compose_push.md create mode 100644 docs/reference/compose_rm.md create mode 100644 docs/reference/compose_run.md create mode 100644 docs/reference/compose_start.md create mode 100644 docs/reference/compose_stop.md create mode 100644 docs/reference/compose_top.md create mode 100644 docs/reference/compose_unpause.md create mode 100644 docs/reference/compose_up.md create mode 100644 docs/reference/docker_compose.yaml create mode 100644 docs/reference/docker_compose_build.yaml create mode 100644 docs/reference/docker_compose_convert.yaml create mode 100644 docs/reference/docker_compose_create.yaml create mode 100644 docs/reference/docker_compose_down.yaml create mode 100644 docs/reference/docker_compose_events.yaml create mode 100644 docs/reference/docker_compose_exec.yaml create mode 100644 docs/reference/docker_compose_kill.yaml create mode 100644 docs/reference/docker_compose_logs.yaml create mode 100644 docs/reference/docker_compose_ls.yaml create mode 100644 docs/reference/docker_compose_pause.yaml create mode 100644 docs/reference/docker_compose_ps.yaml create mode 100644 docs/reference/docker_compose_pull.yaml create mode 100644 docs/reference/docker_compose_push.yaml create mode 100644 docs/reference/docker_compose_rm.yaml create mode 100644 docs/reference/docker_compose_run.yaml create mode 100644 docs/reference/docker_compose_start.yaml create mode 100644 docs/reference/docker_compose_stop.yaml create mode 100644 docs/reference/docker_compose_top.yaml create mode 100644 docs/reference/docker_compose_unpause.yaml create mode 100644 docs/reference/docker_compose_up.yaml create mode 100644 docs/yaml/main/generate.go create mode 100644 docs/yaml/yaml.go diff --git a/builder.Makefile b/builder.Makefile index da3971e4e..be8e0a00e 100644 --- a/builder.Makefile +++ b/builder.Makefile @@ -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 \ No newline at end of file diff --git a/docs/reference/compose.md b/docs/reference/compose.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_convert.md b/docs/reference/compose_convert.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_create.md b/docs/reference/compose_create.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_down.md b/docs/reference/compose_down.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_events.md b/docs/reference/compose_events.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_exec.md b/docs/reference/compose_exec.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_kill.md b/docs/reference/compose_kill.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_logs.md b/docs/reference/compose_logs.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_ls.md b/docs/reference/compose_ls.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_pause.md b/docs/reference/compose_pause.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_pull.md b/docs/reference/compose_pull.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_push.md b/docs/reference/compose_push.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_rm.md b/docs/reference/compose_rm.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_start.md b/docs/reference/compose_start.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_stop.md b/docs/reference/compose_stop.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_unpause.md b/docs/reference/compose_unpause.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/compose_up.md b/docs/reference/compose_up.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml new file mode 100644 index 000000000..3008432e8 --- /dev/null +++ b/docs/reference/docker_compose.yaml @@ -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 + diff --git a/docs/reference/docker_compose_build.yaml b/docs/reference/docker_compose_build.yaml new file mode 100644 index 000000000..1921bd31f --- /dev/null +++ b/docs/reference/docker_compose_build.yaml @@ -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 + diff --git a/docs/reference/docker_compose_convert.yaml b/docs/reference/docker_compose_convert.yaml new file mode 100644 index 000000000..de7c29b87 --- /dev/null +++ b/docs/reference/docker_compose_convert.yaml @@ -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 + diff --git a/docs/reference/docker_compose_create.yaml b/docs/reference/docker_compose_create.yaml new file mode 100644 index 000000000..7fd80b94f --- /dev/null +++ b/docs/reference/docker_compose_create.yaml @@ -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 + diff --git a/docs/reference/docker_compose_down.yaml b/docs/reference/docker_compose_down.yaml new file mode 100644 index 000000000..f0ebc6e63 --- /dev/null +++ b/docs/reference/docker_compose_down.yaml @@ -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 + diff --git a/docs/reference/docker_compose_events.yaml b/docs/reference/docker_compose_events.yaml new file mode 100644 index 000000000..128e78af8 --- /dev/null +++ b/docs/reference/docker_compose_events.yaml @@ -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 + diff --git a/docs/reference/docker_compose_exec.yaml b/docs/reference/docker_compose_exec.yaml new file mode 100644 index 000000000..ed7969df3 --- /dev/null +++ b/docs/reference/docker_compose_exec.yaml @@ -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 + diff --git a/docs/reference/docker_compose_kill.yaml b/docs/reference/docker_compose_kill.yaml new file mode 100644 index 000000000..2312ea153 --- /dev/null +++ b/docs/reference/docker_compose_kill.yaml @@ -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 + diff --git a/docs/reference/docker_compose_logs.yaml b/docs/reference/docker_compose_logs.yaml new file mode 100644 index 000000000..195eb9167 --- /dev/null +++ b/docs/reference/docker_compose_logs.yaml @@ -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 + diff --git a/docs/reference/docker_compose_ls.yaml b/docs/reference/docker_compose_ls.yaml new file mode 100644 index 000000000..ffb4c8540 --- /dev/null +++ b/docs/reference/docker_compose_ls.yaml @@ -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 + diff --git a/docs/reference/docker_compose_pause.yaml b/docs/reference/docker_compose_pause.yaml new file mode 100644 index 000000000..b44c6eef1 --- /dev/null +++ b/docs/reference/docker_compose_pause.yaml @@ -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 + diff --git a/docs/reference/docker_compose_ps.yaml b/docs/reference/docker_compose_ps.yaml new file mode 100644 index 000000000..e0b8579cd --- /dev/null +++ b/docs/reference/docker_compose_ps.yaml @@ -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 + diff --git a/docs/reference/docker_compose_pull.yaml b/docs/reference/docker_compose_pull.yaml new file mode 100644 index 000000000..7960d3a2c --- /dev/null +++ b/docs/reference/docker_compose_pull.yaml @@ -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 + diff --git a/docs/reference/docker_compose_push.yaml b/docs/reference/docker_compose_push.yaml new file mode 100644 index 000000000..92a2068a8 --- /dev/null +++ b/docs/reference/docker_compose_push.yaml @@ -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 + diff --git a/docs/reference/docker_compose_rm.yaml b/docs/reference/docker_compose_rm.yaml new file mode 100644 index 000000000..6e4a896f8 --- /dev/null +++ b/docs/reference/docker_compose_rm.yaml @@ -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 + diff --git a/docs/reference/docker_compose_run.yaml b/docs/reference/docker_compose_run.yaml new file mode 100644 index 000000000..471d08339 --- /dev/null +++ b/docs/reference/docker_compose_run.yaml @@ -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 + diff --git a/docs/reference/docker_compose_start.yaml b/docs/reference/docker_compose_start.yaml new file mode 100644 index 000000000..eea61b7b6 --- /dev/null +++ b/docs/reference/docker_compose_start.yaml @@ -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 + diff --git a/docs/reference/docker_compose_stop.yaml b/docs/reference/docker_compose_stop.yaml new file mode 100644 index 000000000..c47c78df5 --- /dev/null +++ b/docs/reference/docker_compose_stop.yaml @@ -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 + diff --git a/docs/reference/docker_compose_top.yaml b/docs/reference/docker_compose_top.yaml new file mode 100644 index 000000000..95f49262d --- /dev/null +++ b/docs/reference/docker_compose_top.yaml @@ -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 + diff --git a/docs/reference/docker_compose_unpause.yaml b/docs/reference/docker_compose_unpause.yaml new file mode 100644 index 000000000..66cc0a669 --- /dev/null +++ b/docs/reference/docker_compose_unpause.yaml @@ -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 + diff --git a/docs/reference/docker_compose_up.yaml b/docs/reference/docker_compose_up.yaml new file mode 100644 index 000000000..99ebe0518 --- /dev/null +++ b/docs/reference/docker_compose_up.yaml @@ -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 + diff --git a/docs/yaml/main/generate.go b/docs/yaml/main/generate.go new file mode 100644 index 000000000..63792115c --- /dev/null +++ b/docs/yaml/main/generate.go @@ -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()) + } +} diff --git a/docs/yaml/yaml.go b/docs/yaml/yaml.go new file mode 100644 index 000000000..5f7559cbd --- /dev/null +++ b/docs/yaml/yaml.go @@ -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() }