generate reference docs with cli-docs-tool #62

crazy-max · 2025-05-15T18:46:50Z

Generate reference docs similar to other CLI plugins (buildx, compose, scout, ...):

Docs generation is sandboxed using a Dockerfile
Can be tested with make docs
To validate docs you can use Bake: docker buildx bake validate-docs
A GHA workflow has been added to validate docs as well

As follow-up docs team can:

Start adding examples for each command and flag.
Create hugo module on the docs website to vendor model-cli with reference docs.

cc @ArthurFlag

~~Keeping in draft for now until I meet with Arthur tomorrow~~

crazy-max · 2025-05-15T18:49:51Z

go.mod

 	github.com/docker/docker v28.0.1+incompatible
+	github.com/docker/go-connections v0.5.0


This change is not related, seems go mod is not tidy on main. Also don't see any kind of validation for go.mod and vendor in CI.

crazy-max · 2025-05-15T18:57:03Z

Dockerfile

@@ -0,0 +1,49 @@
+# syntax=docker/dockerfile:1
+
+ARG GO_VERSION=1.24


I use Go latest stable for generating docs but I don't see any Go version set on this repo.

Seems when model-cli is released on CI it uses whatever version is shipped in the runner atm:

model-cli/.github/workflows/build.yml

Lines 23 to 26 in 0efa602

- uses: actions/setup-go@v5

with:

go-version-file: go.mod

cache: true

This should be fixed imo.

Agreed. We'll find some spare cycles to address the build stuff in 4.43.

Signed-off-by: CrazyMax <[email protected]>

crazy-max · 2025-05-16T09:46:07Z

.github/workflows/validate.yml

+  push:
+    branches:
+      - 'main'
+      - 'v[0-9]*'


Not sure what branching strategy is in place as I don't see any release branch but just in case, I match it.

The tags are all coming off of main for now (and we're generally backporting those changes to recent releases via modules). We're planning a proper release branch structure starting with 4.43.

ArthurFlag · 2025-05-16T12:31:41Z

@crazy-max I don't seem to be able to merge the docs update into your branch. This might be something only you can do.

crazy-max · 2025-05-16T12:45:47Z

@crazy-max I don't seem to be able to merge the docs update into your branch. This might be something only you can do.

It should be as follow-up when this one is merged and then you could pick your commits from https://github.com/crazy-max/docker-model-cli/pull/1/commits and open a new PR on this repo. Better to keep separation of concerns with this PR generating the docs and yours for docs copy.

doringeman

I remember I saw this before in another repo.
Will these be used by docker/docs?

crazy-max · 2025-05-16T14:46:05Z

I remember I saw this before in another repo. Will these be used by docker/docs?

Yes the go module will be vendored on docs repo similar to buildx, compose cli plugins.

xenoscopic · 2025-05-16T17:48:30Z

.github/workflows/validate.yml

+  push:
+    branches:
+      - 'main'
+      - 'v[0-9]*'


The tags are all coming off of main for now (and we're generally backporting those changes to recent releases via modules). We're planning a proper release branch structure starting with 4.43.

xenoscopic · 2025-05-16T17:49:12Z

Dockerfile

@@ -0,0 +1,49 @@
+# syntax=docker/dockerfile:1
+
+ARG GO_VERSION=1.24


Agreed. We'll find some spare cycles to address the build stuff in 4.43.

xenoscopic · 2025-05-16T17:52:15Z

docs/reference/docker_model.yaml

+    - docker_model_tag.yaml
+    - docker_model_uninstall-runner.yaml
+    - docker_model_version.yaml
+options:


These top-level options are only added to the Model CLI's root command if not running as a CLI plugin (i.e. if invoking docker-model directly). We mostly do this for standalone debugging. We should probably exclude them from the docs, because in official usage as a CLI plugin (i.e. docker model) they'd be options on the top-level docker command (e.g. docker --context mycloudengine model status).

If that's the case they should be marked as hidden similar to https://github.com/docker/buildx/blob/57a1c97c9d9bc2e610364e9da4948c492d4254fe/commands/install.go#L50

Although version should be kept imo

Can you list what commands should be hidden?

xenoscopic · 2025-05-16T17:53:57Z

docs/reference/docker_model_compose.yaml

@@ -0,0 +1,26 @@
+command: docker model compose


It looks like docker_model_compose.yaml files have been excluded from the cname/clink sections in docker_model.yaml. Does that mean they'll be hidden in the generated output? If so, that's perfect, I think we definitely want to exclude the hidden Compose provider commands. (Same question for markdown, but it looks like they're excluded there too 👍 ?)

Yes seems root compose command is hidden:

model-cli/commands/compose.go

Line 23 in 0efa602

c.Hidden = true

$ docker model --help Usage: docker model COMMAND Docker Model Runner Commands: inspect Display detailed information on one model list List the available models that can be run with the Docker Model Runner logs Fetch the Docker Model Runner logs pull Download a model push Upload a model rm Remove models downloaded from Docker Hub run Run a model with the Docker Model Runner status Check if the Docker Model Runner is running tag Tag a model version Show the Docker Model Runner version Run 'docker model COMMAND --help' for more information on a command.

But doesn't look inherited:

$ docker model compose --help Usage: docker model compose [OPTIONS] COMMAND Options: --project-name string compose project name Commands: down up Run 'docker model compose COMMAND --help' for more information on a command.

Because Hidden is set after subcommands are added:

model-cli/commands/compose.go

Lines 18 to 23 in 0efa602

c := &cobra.Command{

Use: "compose EVENT",

}

c.AddCommand(newUpCommand())

c.AddCommand(newDownCommand())

c.Hidden = true

Ok seems cli-docs-tool doesn't handle inheritance for hidden commands so subcommands docs is still generated. I marked all subcommands as hidden in the meantime.

@thaJeztah Wonder if we should handle this, WDYT?

Hm... good one; so ISTR we had some discussion around hidden commands (and to generate things regardless, leaving it to the docs.docker.com repository to decide whether to publish docs for them?)

Opened docker/cli-docs-tool#65

Updated to cli-docs-tool v0.10.0 to fix this issue

xenoscopic · 2025-05-16T17:56:17Z

docs/reference/model.md

+| `--config`          | `string` | `/root/.docker`          | Location of client config files                                                                                                       |
+| `-c`, `--context`   | `string` |                          | Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use") |
+| `-D`, `--debug`     | `bool`   |                          | Enable debug mode                                                                                                                     |
+| `-H`, `--host`      | `list`   |                          | Daemon socket to connect to                                                                                                           |
+| `-l`, `--log-level` | `string` | `info`                   | Set the logging level ("debug", "info", "warn", "error", "fatal")                                                                     |
+| `--tls`             | `bool`   |                          | Use TLS; implied by --tlsverify                                                                                                       |
+| `--tlscacert`       | `string` | `/root/.docker/ca.pem`   | Trust certs signed only by this CA                                                                                                    |
+| `--tlscert`         | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file                                                                                                          |
+| `--tlskey`          | `string` | `/root/.docker/key.pem`  | Path to TLS key file                                                                                                                  |
+| `--tlsverify`       | `bool`   |                          | Use TLS and verify the remote                                                                                                         |


I would also exclude all of these top-level docker flags. If the generation is invoked via docker model instead of docker-model, do they disappear?

Yes docker global flags are registered in standalone mode:

model-cli/commands/root.go

Lines 86 to 91 in 0efa602

// Initialize client options and register their flags if running in

// standalone mode.

if plugin.RunningStandalone() {

globalOptions = flags.NewClientOptions()

globalOptions.InstallFlags(rootCmd.Flags())

}

I will look if we can omit them for our docs

Should be good now

thaJeztah · 2025-05-19T12:15:11Z

docs/reference/docker_model.yaml

@crazy-max do we want the yaml docs to be separate from the markdown ones? (or even; could we generate them dynamically as we did for buildx?).

Mostly considering that these unlikely are useful for readers on GitHub (and the reverse; docs.docker.com doesn't use the markdown ones directly).

I preferred to keep yaml generation in this repo so it's easier to vendor changes on docs repo. So if we want to vendor specific commit for the module we don't need extra work for docs team. Same as compose repo.

Gotcha; ISTR for compose this caused some complication with other markdown files that still had to be used? Wondering if the YAML should be in a separate directory.

Not a blocker though; mostly something we should probably look at to separate these 🤔

I think I would do the same on buildx repo at some point. Otherwise people need to first clone plugin project, run make docs, copy over generated yaml files in docs repo and update vendor.

and the reverse; docs.docker.com doesn't use the markdown ones directly).

For this hugo seems to always include mardown files even if excluded:

https://github.com/docker/docs/blob/f4f1a45ec9b71543f6a2fd0b567637280ec83a96/hugo.yaml#L337-L342

https://github.com/docker/docs/tree/f4f1a45ec9b71543f6a2fd0b567637280ec83a96/_vendor/github.com/docker/compose/v2/docs/reference

Yeah, that's a bit why I was considering that as well, because docs only uses the YAML files? But because they're in the same directory would now pull in both; was wondering if putting it separate would allow only pulling in the yaml 🤔 (although possibly it only looks as the module as a whole, and all markdown in all paths?)

Signed-off-by: CrazyMax <[email protected]>

crazy-max · 2025-05-21T12:12:19Z

@doringeman @xenoscopic Are we good to merge this so Docs team can start working on examples? Thanks!

kiview · 2025-05-21T14:15:06Z

Synced with @xenoscopic, good to merge 👍

xenoscopic

LGTM!

* fix go.mod Signed-off-by: CrazyMax <[email protected]> * generate reference docs with cli-docs-tool Signed-off-by: CrazyMax <[email protected]> * mark command as experimental Signed-off-by: CrazyMax <[email protected]> * docs: don't register global docker flags Signed-off-by: CrazyMax <[email protected]> --------- Signed-off-by: CrazyMax <[email protected]>

@tag

## Description Adds model-cli reference docs. ## Related issues or tickets * docker/model-cli#62 * docker/model-cli#69 ## Reviews   - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: CrazyMax <[email protected]> Co-authored-by: ArthurFlag <[email protected]>

@tag

## Description Adds model-cli reference docs. ## Related issues or tickets * docker/model-cli#62 * docker/model-cli#69 ## Reviews   - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: CrazyMax <[email protected]> Co-authored-by: ArthurFlag <[email protected]>

crazy-max commented May 15, 2025

View reviewed changes

crazy-max force-pushed the ref-docs branch from af0a68f to e98b48d Compare May 15, 2025 18:51

crazy-max commented May 15, 2025

View reviewed changes

crazy-max marked this pull request as ready for review May 16, 2025 08:31

fix go.mod

5b942f5

Signed-off-by: CrazyMax <[email protected]>

crazy-max force-pushed the ref-docs branch from e98b48d to eb0ba33 Compare May 16, 2025 09:36

crazy-max commented May 16, 2025

View reviewed changes

crazy-max force-pushed the ref-docs branch from eb0ba33 to 51cf3d4 Compare May 16, 2025 09:47

kiview requested review from doringeman and xenoscopic May 16, 2025 11:33

doringeman approved these changes May 16, 2025

View reviewed changes

xenoscopic reviewed May 16, 2025

View reviewed changes

thaJeztah reviewed May 19, 2025

View reviewed changes

crazy-max mentioned this pull request May 19, 2025

skip hidden command recursively docker/cli-docs-tool#65

Merged

crazy-max added 3 commits May 19, 2025 15:50

generate reference docs with cli-docs-tool

b804d65

Signed-off-by: CrazyMax <[email protected]>

mark command as experimental

31907d5

Signed-off-by: CrazyMax <[email protected]>

docs: don't register global docker flags

aa70df6

Signed-off-by: CrazyMax <[email protected]>

crazy-max force-pushed the ref-docs branch from cd5ca90 to aa70df6 Compare May 19, 2025 13:51

xenoscopic approved these changes May 21, 2025

View reviewed changes

kiview merged commit 0ef53e8 into docker:main May 21, 2025
1 check passed

This was referenced May 21, 2025

Add docker model ps #63

Merged

model-cli reference docs docker/docs#22681

Merged

crazy-max deleted the ref-docs branch May 22, 2025 12:44

crazy-max mentioned this pull request Jul 6, 2025

add model package docker/packaging#230

Merged

		github.com/docker/docker v28.0.1+incompatible
		github.com/docker/go-connections v0.5.0

		@@ -0,0 +1,49 @@
		# syntax=docker/dockerfile:1

		ARG GO_VERSION=1.24

	- uses: actions/setup-go@v5
	with:
	go-version-file: go.mod
	cache: true

	c := &cobra.Command{
	Use: "compose EVENT",
	}
	c.AddCommand(newUpCommand())
	c.AddCommand(newDownCommand())
	c.Hidden = true

	// Initialize client options and register their flags if running in
	// standalone mode.
	if plugin.RunningStandalone() {
	globalOptions = flags.NewClientOptions()
	globalOptions.InstallFlags(rootCmd.Flags())
	}

generate reference docs with cli-docs-tool #62

generate reference docs with cli-docs-tool #62

Uh oh!

Conversation

crazy-max commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ArthurFlag commented May 16, 2025

Uh oh!

crazy-max commented May 16, 2025

Uh oh!

doringeman left a comment

Choose a reason for hiding this comment

Uh oh!

crazy-max commented May 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crazy-max commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kiview commented May 21, 2025

Uh oh!

xenoscopic left a comment

crazy-max commented May 15, 2025 •

edited

Loading

crazy-max May 15, 2025 •

edited

Loading

crazy-max May 19, 2025 •

edited

Loading

crazy-max May 19, 2025 •

edited

Loading

crazy-max May 19, 2025 •

edited

Loading

crazy-max May 19, 2025 •

edited

Loading

crazy-max commented May 21, 2025 •

edited

Loading