Merge pull request #1757 from ndeloof/docs

update reference docs

Author: ndeloof

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

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,

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")

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.

docs/reference/compose_cp.md

@@ -0,0 +1,4 @@
+
+## Description
+
+Prints the public port for a port binding.

docs/reference/compose_images.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)          
+```

docs/reference/compose_port.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).

docs/reference/compose_ps.md

@@ -1,4 +1,5 @@
 
+## Description
 
 Runs a one-time command against a service.