Generate CLI docs from Go code

cmd/cog/cog.go

@@ -1,8 +1,10 @@
 package main
 
 import (
+	"log"
 	"github.com/replicate/cog/pkg/cli"
 	"github.com/replicate/cog/pkg/util/console"
+	"github.com/spf13/cobra/doc"
 )
 
 func main() {
@@ -11,6 +13,11 @@ func main() {
 		console.Fatalf("%f", err)
 	}
 
+	err = doc.GenMarkdownTree(cmd, "./docs/tmp")
+	if err != nil {
+		log.Fatal(err)
+	}
+
 	if err = cmd.Execute(); err != nil {
 		console.Fatalf("%s", err)
 	}

docs/cli.md

@@ -0,0 +1,248 @@
+# Cog CLI reference
+
+
+<!-- Do not manually edit this file! It is auto-generated from Go source code. -->
+
+
+This document defines the command-line interface for Cog.
+
+
+## `cog init`
+
+Scaffold a new Cog model
+
+### Synopsis
+
+This command sets up a new Cog project in the current directory, with files to get you started:
+
+- cog.yaml, for definining Python and system-level dependencies
+- predict.py, for defining the Prediction API for your model
+- .dockerignore, to keep large unneeded files out of your published model
+- .github/workflows/push.yaml, a GitHub Actions workflow to package and push your model
+
+```
+cog init [flags]
+```
+
+### Examples
+
+```
+mkdir my-model && cd my-model && cog init
+```
+
+### Options
+
+```
+  -h, --help   help for init
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```
+
+
+## `cog build`
+
+Build an image from cog.yaml
+
+### Synopsis
+
+This command builds a Docker image from your project's cog.yaml.
+
+This bakes your model's code, the trained weights, and the Docker environment 
+into a Docker image which can serve predictions with an HTTP server, and can be 
+deployed to anywhere that Docker runs to serve real-time predictions.
+
+```
+cog build [flags]
+```
+
+### Options
+
+```
+  -h, --help                         help for build
+      --no-cache                     Do not use cache when building the image
+      --openapi-schema string        Load OpenAPI schema from a file
+      --progress string              Set type of build progress output, 'auto' (default), 'tty' or 'plain' (default "auto")
+      --secret stringArray           Secrets to pass to the build environment in the form 'id=foo,src=/path/to/file'
+      --separate-weights             Separate model weights from code in image layers
+  -t, --tag string                   A name for the built image in the form 'repository:tag'
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```
+
+
+## `cog run`
+
+Run a command inside a Docker environment
+
+### Synopsis
+
+Run a command inside a Docker environment.
+
+The command will be run with the current directory mounted as a volume.
+
+Use commands like "cog run bash" or "cog run python" to access your 
+model's runtime environment, so you can interact with it in a Python 
+shell, install system dependencies, etc.
+
+```
+cog run <command> [arg...] [flags]
+```
+
+### Examples
+
+```
+# Run Python in your container using the Python version you set in cog.yaml
+cog run python
+
+# Access an interactive shell inside your container
+cog run bash
+```
+
+### Options
+
+```
+  -e, --env stringArray              Environment variables, in the form name=value
+      --gpus docker run --gpus       GPU devices to add to the container, in the same format as docker run --gpus.
+  -h, --help                         help for run
+      --progress string              Set type of build progress output, 'auto' (default), 'tty' or 'plain' (default "auto")
+  -p, --publish stringArray          Publish a container's port to the host, e.g. -p 8000
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```
+
+
+## `cog predict`
+
+Run a prediction
+
+### Synopsis
+
+This command runs a prediction.
+
+If 'image' is passed, it will run the prediction on that Docker image.
+It must be an image that has been built by Cog.
+
+Otherwise, it will build the model in the current directory and run
+the prediction on that.
+
+```
+cog predict [image] [flags]
+```
+
+### Examples
+
+```
+cog predict -i mask_image=@my_mask.png -i meaning_of_life=42
+```
+
+### Options
+
+```
+  -e, --env stringArray              Environment variables, in the form name=value
+      --gpus docker run --gpus       GPU devices to add to the container, in the same format as docker run --gpus.
+  -h, --help                         help for predict
+  -i, --input stringArray            Inputs, in the form name=value. if value is prefixed with @, then it is read from a file on disk. E.g. -i path=@image.jpg
+  -o, --output string                Output path
+      --progress string              Set type of build progress output, 'auto' (default), 'tty' or 'plain' (default "auto")
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```
+
+
+## `cog login`
+
+Log in to the Replicate Docker registry
+
+### Synopsis
+
+Log in to the Replicate Docker registry.
+
+This will allow you to push and pull Docker images from the Replicate registry.
+
+```
+cog login [flags]
+```
+
+### Examples
+
+```
+# log in interactively via web browser
+cog login
+
+# pipe token from environment variable
+echo $REPLICATE_API_TOKEN | cog login --token-stdin
+
+# log in to a custom registry
+cog login --registry=my-custom-docker-registry.com
+```
+
+### Options
+
+```
+  -h, --help          help for login
+      --token-stdin   Pass login token on stdin instead of opening a browser. You can find your Replicate login token at https://replicate.com/auth/token
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```
+
+
+## `cog push`
+
+Build and push model in current directory to a Docker registry
+
+```
+cog push [IMAGE] [flags]
+```
+
+### Examples
+
+```
+cog push r8.im/your-username/hotdog-detector
+```
+
+### Options
+
+```
+  -h, --help                         help for push
+      --no-cache                     Do not use cache when building the image
+      --openapi-schema string        Load OpenAPI schema from a file
+      --progress string              Set type of build progress output, 'auto' (default), 'tty' or 'plain' (default "auto")
+      --secret stringArray           Secrets to pass to the build environment in the form 'id=foo,src=/path/to/file'
+      --separate-weights             Separate model weights from code in image layers
+      --use-cuda-base-image string   Use Nvidia CUDA base image, 'true' (default) or 'false' (use python base image). False results in a smaller image but may cause problems for non-torch projects (default "auto")
+```
+
+### Options inherited from parent commands
+
+```
+      --debug     Show debugging output
+      --version   Show version of Cog
+```

go.mod

@@ -60,6 +60,7 @@ require (
 	github.com/cespare/xxhash/v2 v2.1.2 // indirect
 	github.com/charithe/durationcheck v0.0.10 // indirect
 	github.com/chavacava/garif v0.1.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.3 // indirect
 	github.com/curioswitch/go-reassign v0.2.0 // indirect
 	github.com/daixiang0/gci v0.12.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
@@ -165,6 +166,7 @@ require (
 	github.com/quasilyte/regex/syntax v0.0.0-20210819130434-b3f0c404a727 // indirect
 	github.com/quasilyte/stdinfo v0.0.0-20220114132959-f7386bf02567 // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/ryancurrah/gomodguard v1.3.0 // indirect
 	github.com/ryanrolds/sqlclosecheck v0.5.1 // indirect
 	github.com/sanposhiho/wastedassign/v2 v2.0.7 // indirect

go.sum

@@ -121,6 +121,7 @@ github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5P
 github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
+github.com/cpuguy83/go-md2man/v2 v2.0.3 h1:qMCsGGgs+MAzDFyp9LpAe1Lqy/fY/qCovCm0qnXZOBM=
 github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.18 h1:n56/Zwd5o6whRC5PMGretI4IdRLlmBXYNjScPaBgsbY=
 github.com/creack/pty v1.1.18/go.mod h1:MOBLtS5ELjhRRrroQr9kyvTxUAFNvYEK993ew/Vr4O4=
@@ -512,6 +513,7 @@ github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFR
 github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
 github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryancurrah/gomodguard v1.3.0 h1:q15RT/pd6UggBXVBuLps8BXRvl5GPBcwVA7BJHMLuTw=
 github.com/ryancurrah/gomodguard v1.3.0/go.mod h1:ggBxb3luypPEzqVtq33ee7YSN35V28XeGnid8dnni50=

mkdocs.yml

@@ -5,6 +5,7 @@ nav:
   - README: README.md
   - Getting Started: getting-started.md
   - Using your own model: getting-started-own-model.md
+  - Command-line interface (CLI): cli.md
   - YAML spec: yaml.md
   - Prediction API: python.md
   - Training API: training.md

pkg/cli/build.go

@@ -25,6 +25,11 @@ func newBuildCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "build",
 		Short: "Build an image from cog.yaml",
+		Long: `This command builds a Docker image from your project's cog.yaml.
+
+This bakes your model's code, the trained weights, and the Docker environment 
+into a Docker image which can serve predictions with an HTTP server, and can be 
+deployed to anywhere that Docker runs to serve real-time predictions.`,
 		Args:  cobra.NoArgs,
 		RunE:  buildCommand,
 	}

pkg/cli/init.go

@@ -29,7 +29,14 @@
 	var cmd = &cobra.Command{
 		Use:        "init",
 		SuggestFor: []string{"new", "start"},
-		Short:      "Configure your project for use with Cog",
+		Short:      "Scaffold a new Cog model",
+		Long: `This command sets up a new Cog project in the current directory, with files to get you started:
+
+- cog.yaml, for definining Python and system-level dependencies
+- predict.py, for defining the Prediction API for your model
+- .dockerignore, to keep large unneeded files out of your published model
+- .github/workflows/push.yaml, a GitHub Actions workflow to package and push your model`,
+		Example: `mkdir my-model && cd my-model && cog init`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return initCommand(args)
 		},

pkg/cli/login.go

@@ -27,7 +27,18 @@ func newLoginCommand() *cobra.Command {
 	var cmd = &cobra.Command{
 		Use:        "login",
 		SuggestFor: []string{"auth", "authenticate", "authorize"},
-		Short:      "Log in to Replicate Docker registry",
+		Short:      "Log in to the Replicate Docker registry",
+		Long: `Log in to the Replicate Docker registry.
+
+This will allow you to push and pull Docker images from the Replicate registry.`,
+		Example: `# log in interactively via web browser
+cog login
+
+# pipe token from environment variable
+echo $REPLICATE_API_TOKEN | cog login --token-stdin
+
+# log in to a custom registry
+cog login --registry=my-custom-docker-registry.com`,
 		RunE:       login,
 		Args:       cobra.MaximumNArgs(0),
 	}

pkg/cli/predict.go

@@ -33,13 +33,14 @@ func newPredictCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "predict [image]",
 		Short: "Run a prediction",
-		Long: `Run a prediction.
+		Long: `This command runs a prediction.
 
 If 'image' is passed, it will run the prediction on that Docker image.
 It must be an image that has been built by Cog.
 
 Otherwise, it will build the model in the current directory and run
 the prediction on that.`,
+		Example: "cog predict -i mask_image=@my_mask.png -i meaning_of_life=42",
 		RunE:       cmdPredict,
 		Args:       cobra.MaximumNArgs(1),
 		SuggestFor: []string{"infer"},

pkg/cli/run.go

@@ -25,6 +25,18 @@ func newRunCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run <command> [arg...]",
 		Short: "Run a command inside a Docker environment",
+		Long: `Run a command inside a Docker environment.
+
+The command will be run with the current directory mounted as a volume.
+
+Use commands like "cog run bash" or "cog run python" to access your 
+model's runtime environment, so you can interact with it in a Python 
+shell, install system dependencies, etc.`,
+		Example: `# Run Python in your container using the Python version you set in cog.yaml
+cog run python
+
+# Access an interactive shell inside your container
+cog run bash`,
 		RunE:  run,
 		Args:  cobra.MinimumNArgs(1),
 	}