Merge pull request #1757 from ndeloof/docs

ndeloof · web-flow · commit b0a66356e098 · 2021-06-09T07:31:22.000+02:00
update reference docs
diff --git a/cli/cmd/compose/build.go b/cli/cmd/compose/build.go
@@ -64,7 +64,7 @@ func buildCommand(p *projectOptions, backend compose.Service) *cobra.Command {
 	}
 	cmd.Flags().BoolVarP(&opts.quiet, "quiet", "q", false, "Don't print anything to STDOUT")
 	cmd.Flags().BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image.")
-	cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "tty")`)
+	cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "noTty")`)
 	cmd.Flags().StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables for services.")
 	cmd.Flags().Bool("parallel", true, "Build images in parallel. DEPRECATED")
 	cmd.Flags().MarkHidden("parallel") //nolint:errcheck
diff --git a/cli/cmd/compose/exec.go b/cli/cmd/compose/exec.go
@@ -36,7 +36,7 @@ type execOpts struct {
 	environment []string
 	workingDir  string
 
-	tty        bool
+	noTty      bool
 	user       string
 	detach     bool
 	index      int
@@ -68,7 +68,7 @@ func execCommand(p *projectOptions, backend compose.Service) *cobra.Command {
 	runCmd.Flags().IntVar(&opts.index, "index", 1, "index of the container if there are multiple instances of a service [default: 1].")
 	runCmd.Flags().BoolVarP(&opts.privileged, "privileged", "", false, "Give extended privileges to the process.")
 	runCmd.Flags().StringVarP(&opts.user, "user", "u", "", "Run the command as this user.")
-	runCmd.Flags().BoolVarP(&opts.tty, "", "T", false, "Disable pseudo-tty allocation. By default `docker compose exec` allocates a TTY.")
+	runCmd.Flags().BoolVarP(&opts.noTty, "", "T", false, "Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.")
 	runCmd.Flags().StringVarP(&opts.workingDir, "workdir", "w", "", "Path to workdir directory for this command.")
 
 	runCmd.Flags().SetInterspersed(false)
@@ -85,7 +85,7 @@ func runExec(ctx context.Context, backend compose.Service, opts execOpts) error
 		Service:     opts.service,
 		Command:     opts.command,
 		Environment: opts.environment,
-		Tty:         !opts.tty,
+		Tty:         !opts.noTty,
 		User:        opts.user,
 		Privileged:  opts.privileged,
 		Index:       opts.index,
diff --git a/cli/cmd/compose/run.go b/cli/cmd/compose/run.go
@@ -132,7 +132,7 @@ func runCommand(p *projectOptions, backend compose.Service) *cobra.Command {
 	flags.StringArrayVarP(&opts.environment, "env", "e", []string{}, "Set environment variables")
 	flags.StringArrayVarP(&opts.labels, "labels", "l", []string{}, "Add or override a label")
 	flags.BoolVar(&opts.Remove, "rm", false, "Automatically remove the container when it exits")
-	flags.BoolVarP(&opts.noTty, "no-TTY", "T", false, "Disable pseudo-tty allocation. By default docker compose run allocates a TTY")
+	flags.BoolVarP(&opts.noTty, "no-TTY", "T", false, "Disable pseudo-noTty allocation. By default docker compose run allocates a TTY")
 	flags.StringVar(&opts.name, "name", "", " Assign a name to the container")
 	flags.StringVarP(&opts.user, "user", "u", "", "Run as specified username or uid")
 	flags.StringVarP(&opts.workdir, "workdir", "w", "", "Working directory inside the container")
diff --git a/docs/reference/compose_build.md b/docs/reference/compose_build.md
@@ -0,0 +1,12 @@
+
+## Description
+
+Services are built once and then tagged, by default as `project_service`. 
+
+If the Compose file specifies an
+[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image) name, 
+the image is tagged with that name, substituting any variables beforehand. See
+[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).
+
+If you change a service's `Dockerfile` or the contents of its build directory, 
+run `docker compose build` to rebuild it.
diff --git a/docs/reference/compose_cp.md b/docs/reference/compose_cp.md
diff --git a/docs/reference/compose_images.md b/docs/reference/compose_images.md
diff --git a/docs/reference/compose_port.md b/docs/reference/compose_port.md
@@ -0,0 +1,4 @@
+
+## Description
+
+Prints the public port for a port binding.
diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md
@@ -1,4 +1,11 @@
 
 ## Description
 
-Lists containers for a Compose project.
+Lists containers for a Compose project, with current status and exposed ports.
+
+```
+$ docker compose ps
+NAME                SERVICE             STATUS              PORTS
+example_foo_1       foo                 running (healthy)   0.0.0.0:8000->80/tcp
+example_bar_1       bar                 exited (1)          
+```
diff --git a/docs/reference/compose_restart.md b/docs/reference/compose_restart.md
@@ -0,0 +1,10 @@
+Restarts all stopped and running services.
+
+If you make changes to your `compose.yml` configuration, these changes are not reflected 
+after running this command. For example, changes to environment variables (which are added 
+after a container is built, but before the container's command is executed) are not updated 
+after restarting.
+
+If you are looking to configure a service's restart policy, please refer to
+[restart](https://github.com/compose-spec/compose-spec/blob/master/spec.md#restart)
+or [restart_policy](https://github.com/compose-spec/compose-spec/blob/master/deploy.md#restart_policy).
diff --git a/docs/reference/compose_run.md b/docs/reference/compose_run.md
@@ -1,4 +1,5 @@
 
+## Description
 
 Runs a one-time command against a service. 
 
diff --git a/docs/reference/compose_top.md b/docs/reference/compose_top.md
@@ -7,7 +7,7 @@ Displays the running processes.
 
 ```
 $ docker compose top
-sample_foo_1
+example_foo_1
 UID    PID      PPID     C    STIME   TTY   TIME       CMD
 root   142353   142331   2    15:33   ?     00:00:00   ping localhost -c 5 
 ```
diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml
@@ -57,6 +57,7 @@ plink: docker.yaml
 cname:
   - docker compose build
   - docker compose convert
+  - docker compose cp
   - docker compose create
   - docker compose down
   - docker compose events
@@ -81,6 +82,7 @@ cname:
 clink:
   - docker_compose_build.yaml
   - docker_compose_convert.yaml
+  - docker_compose_cp.yaml
   - docker_compose_create.yaml
   - docker_compose_down.yaml
   - docker_compose_events.yaml
diff --git a/docs/reference/docker_compose_build.yaml b/docs/reference/docker_compose_build.yaml
@@ -1,6 +1,11 @@
 command: docker compose build
 short: Build or rebuild services
-long: Build or rebuild services
+long: "Services are built once and then tagged, by default as `project_service`. \n\nIf
+    the Compose file specifies an\n[image](https://github.com/compose-spec/compose-spec/blob/master/spec.md#image)
+    name, \nthe image is tagged with that name, substituting any variables beforehand.
+    See\n[variable interpolation](https://github.com/compose-spec/compose-spec/blob/master/spec.md#interpolation).\n\nIf
+    you change a service's `Dockerfile` or the contents of its build directory, \nrun
+    `docker compose build` to rebuild it."
 usage: docker compose build [SERVICE...]
 pname: docker compose
 plink: docker_compose.yaml
@@ -73,7 +78,7 @@ options:
   - option: progress
     value_type: string
     default_value: auto
-    description: Set type of progress output ("auto", "plain", "tty")
+    description: Set type of progress output ("auto", "plain", "noTty")
     deprecated: false
     experimental: false
     experimentalcli: false
diff --git a/docs/reference/docker_compose_cp.yaml b/docs/reference/docker_compose_cp.yaml
@@ -0,0 +1,54 @@
+command: docker compose cp
+short: Copy files/folders between a service container and the local filesystem
+long: Copy files/folders between a service container and the local filesystem
+usage: |-
+    docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH|-
+    	docker compose cp [OPTIONS] SRC_PATH|- SERVICE:DEST_PATH
+pname: docker compose
+plink: docker_compose.yaml
+options:
+  - option: all
+    value_type: bool
+    default_value: "false"
+    description: Copy to all the containers of the service.
+    deprecated: false
+    experimental: false
+    experimentalcli: false
+    kubernetes: false
+    swarm: false
+  - option: archive
+    shorthand: a
+    value_type: bool
+    default_value: "false"
+    description: Archive mode (copy all uid/gid information)
+    deprecated: false
+    experimental: false
+    experimentalcli: false
+    kubernetes: false
+    swarm: false
+  - option: follow-link
+    shorthand: L
+    value_type: bool
+    default_value: "false"
+    description: Always follow symbol link in SRC_PATH
+    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
+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
@@ -13,7 +13,7 @@ options:
     value_type: bool
     default_value: "false"
     description: |
-        Disable pseudo-tty allocation. By default `docker compose exec` allocates a TTY.
+        Disable pseudo-TTY allocation. By default `docker compose exec` allocates a TTY.
     deprecated: false
     experimental: false
     experimentalcli: false
diff --git a/docs/reference/docker_compose_port.yaml b/docs/reference/docker_compose_port.yaml
@@ -1,6 +1,6 @@
 command: docker compose port
 short: Print the public port for a port binding.
-long: Print the public port for a port binding.
+long: Prints the public port for a port binding.
 usage: docker compose port [options] [--] SERVICE PRIVATE_PORT
 pname: docker compose
 plink: docker_compose.yaml
diff --git a/docs/reference/docker_compose_ps.yaml b/docs/reference/docker_compose_ps.yaml
@@ -1,6 +1,9 @@
 command: docker compose ps
 short: List containers
-long: Lists containers for a Compose project.
+long: "Lists containers for a Compose project, with current status and exposed ports.\n\n```\n$
+    docker compose ps\nNAME                SERVICE             STATUS              PORTS\nexample_foo_1
+    \      foo                 running (healthy)   0.0.0.0:8000->80/tcp\nexample_bar_1
+    \      bar                 exited (1)          \n```"
 usage: docker compose ps
 pname: docker compose
 plink: docker_compose.yaml
diff --git a/docs/reference/docker_compose_run.yaml b/docs/reference/docker_compose_run.yaml
@@ -1,6 +1,31 @@
 command: docker compose run
 short: Run a one-off command on a service.
-long: Run a one-off command on a service.
+long: "Runs a one-time command against a service. \n\nthe following command starts
+    the `web` service and runs `bash` as its command.\n`docker compose run web bash`\n\nCommands
+    you use with run start in new containers with configuration defined by that of
+    the service,\nincluding volumes, links, and other details. However, there are
+    two important differences:\n\nFirst, the command passed by `run` overrides the
+    command defined in the service configuration. For example, if the \n`web` service
+    configuration is started with `bash`, then `docker compose run web python app.py`
+    overrides it with \n`python app.py`.\n\nThe second difference is that the `docker
+    compose run` command does not create any of the ports specified in the \nservice
+    configuration. This prevents port collisions with already-open ports. If you do
+    want the service’s ports \nto be created and mapped to the host, specify the `--service-ports`\n\n```\ndocker
+    compose run --service-ports web python manage.py shell\n```\n\nAlternatively,
+    manual port mapping can be specified with the `--publish` or `-p` options, just
+    as when using docker run:\n\n```\ndocker compose run --publish 8080:80 -p 2022:22
+    -p 127.0.0.1:2021:21 web python manage.py shell\n```\n\n\nIf you start a service
+    configured with links, the run command first checks to see if the linked service
+    is running \nand starts the service if it is stopped. Once all the linked services
+    are running, the run executes the command you \npassed it. For example, you could
+    run:\n\n```\ndocker compose run db psql -h db -U docker\n```\n\nThis opens an
+    interactive PostgreSQL shell for the linked `db` container.\n\nIf you do not want
+    the run command to start linked containers, use the `--no-deps` flag:\n\n```\ndocker
+    compose run --no-deps web python manage.py shell\n```\n\nIf you want to remove
+    the container after running while overriding the container’s restart policy, use
+    the `--rm` flag:\n\n```\ndocker compose run --rm web python manage.py db upgrade\n```\n\nThis
+    runs a database upgrade script, and removes the container when finished running,
+    even if a restart policy is \nspecified in the service configuration."
 usage: docker compose run [options] [-v VOLUME...] [-p PORT...] [-e KEY=VAL...] [-l
     KEY=VALUE...] SERVICE [COMMAND] [ARGS...]
 pname: docker compose
@@ -57,7 +82,7 @@ options:
     value_type: bool
     default_value: "false"
     description: |
-        Disable pseudo-tty allocation. By default docker compose run allocates a TTY
+        Disable pseudo-noTty allocation. By default docker compose run allocates a TTY
     deprecated: false
     experimental: false
     experimentalcli: false
diff --git a/docs/reference/docker_compose_top.yaml b/docs/reference/docker_compose_top.yaml
@@ -4,7 +4,7 @@ long: Displays the running processes.
 usage: docker compose top
 pname: docker compose
 plink: docker_compose.yaml
-examples: "```\n$ docker compose top\nsample_foo_1\nUID    PID      PPID     C    STIME
+examples: "```\n$ docker compose top\nexample_foo_1\nUID    PID      PPID     C    STIME
     \  TTY   TIME       CMD\nroot   142353   142331   2    15:33   ?     00:00:00
     \  ping localhost -c 5 \n```"
 deprecated: false

Original file line number	Diff line number	Diff line change
`@@ -64,7 +64,7 @@ func buildCommand(p projectOptions, backend compose.Service) cobra.Command {`
`64`	`64`	`}`
`65`	`65`	`cmd.Flags().BoolVarP(&opts.quiet, "quiet", "q", false, "Don't print anything to STDOUT")`
`66`	`66`	`cmd.Flags().BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image.")`
`67`		- cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "tty")`)
	`67`	+ cmd.Flags().StringVar(&opts.progress, "progress", "auto", `Set type of progress output ("auto", "plain", "noTty")`)
`68`	`68`	`cmd.Flags().StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables for services.")`
`69`	`69`	`cmd.Flags().Bool("parallel", true, "Build images in parallel. DEPRECATED")`
`70`	`70`	`cmd.Flags().MarkHidden("parallel") //nolint:errcheck`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
++
 +## Description
++
 +Prints the public port for a port binding.
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`
	`2`	`+## Description`
`2`	`3`
`3`	`4`	`Runs a one-time command against a service.`
`4`	`5`