Merge pull request #1407 from docker/yamldocs

generate reference documentation

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

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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
+

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())
+	}
+}

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() }