From 54896155f7a6a7beb7ad3ec5d98bce487e40fbae Mon Sep 17 00:00:00 2001 From: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> Date: Tue, 7 Oct 2025 08:37:24 -0700 Subject: [PATCH] scout: fix watch docs (#23506) ## Description Fixes the generated scout watch docs to use examples from the upstream markdown, instead of the yaml. When previously updated, only the markdown was updated upstream and not the CLI source which generates the yaml. - Added new layout for the scout cli, based on the generic cli layout. The new layout uses the more extensive markdown examples if present, otherwise use the examples from the yaml. - Updated the scout watch topic to use the new layout Once fixed upstream, will have a follow up to most likely revert this. https://deploy-preview-23506--docsdocker.netlify.app/reference/cli/docker/scout/watch/#examples ## Related issues or tickets Original PR to update the version: #23485. The markdown was updated but not the yaml. Upstream fix: https://github.com/docker/scout-cli-plugin/pull/713 ## Reviews - [ ] Editorial review Signed-off-by: Craig Osterhout --- content/reference/cli/docker/scout/watch.md | 3 +- layouts/_default/scout-cli.html | 287 ++++++++++++++++++++ 2 files changed, 289 insertions(+), 1 deletion(-) create mode 100644 layouts/_default/scout-cli.html diff --git a/content/reference/cli/docker/scout/watch.md b/content/reference/cli/docker/scout/watch.md index ec817aaaa3..c9e1506f70 100644 --- a/content/reference/cli/docker/scout/watch.md +++ b/content/reference/cli/docker/scout/watch.md @@ -1,10 +1,11 @@ --- datafolder: scout-cli datafile: docker_scout_watch +markdownfile: scout_watch.md aliases: - /engine/reference/commandline/scout_watch title: docker scout watch -layout: cli +layout: scout-cli --- " }} + {{ if gt (len $parts) 1 }} + {{ $contentAfterMarker := index $parts 1 }} + {{ $contentAfterMarker = strings.TrimLeft "\n" $contentAfterMarker }} + {{ if gt (len (strings.TrimSpace $contentAfterMarker)) 0 }} + {{ $useMarkdownContent = true }} + {{/* Skip markdown description section if it exists, use only content after it */}} + {{ if strings.Contains $contentAfterMarker "## Examples" }} + {{/* If there's an Examples section, split on it and use everything from Examples onward */}} + {{ $examplesParts := split $contentAfterMarker "## Examples" }} + {{ if gt (len $examplesParts) 1 }} + {{ $markdownContent = printf "## Examples%s" (index $examplesParts 1) }} + {{ else }} + {{ $markdownContent = $contentAfterMarker }} + {{ end }} + {{ else }} + {{/* No Examples section, use all content but skip Description if present */}} + {{ if strings.HasPrefix (strings.TrimSpace $contentAfterMarker) "## Description" }} + {{/* Very simple approach: just use empty content if it starts with Description */}} + {{ $markdownContent = "" }} + {{ else }} + {{ $markdownContent = $contentAfterMarker }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} + {{ end }} + + {{ .Store.Set "headings" slice }} + {{ .Store.Set "subheadings" slice }} +
+
+ {{ partial "breadcrumbs.html" . }} +

{{ .Title }}

+
+ + + {{ with $data.short }} + + + + + {{ end }} + {{ with $data.usage }} + + + + + {{ end }} + {{ with $data.aliases }} + {{ $aliases := strings.Replace . (fmt.Printf "%s, " page.Title) "" }} + + + + + {{ end }} + +
Description{{ . }}
Usage{{ . }}
+ Aliases + {{ partialCached "tooltip.html" "An alias is a short or memorable alternative for a longer command." "cli-alias" }} + +
+ {{ range (strings.Split $aliases ", ") }} + {{ . }} + {{ end }} +
+
+
+ {{ .Content }} + {{ if $data.deprecated }} + {{ markdownify ` +> [!WARNING] +> This command is deprecated +> +> It may be removed in a future Docker version. For more information, see the +> [Docker roadmap](https://github.com/docker/roadmap/issues/209)` + }} + {{ end }} + {{ if or $data.experimental $data.experimentalcli }} + {{ markdownify ` +{{% experimental %}} + +**This command is experimental.** + +Experimental features are intended for testing and feedback as their +functionality or design may change between releases without warning or +can be removed entirely in a future release. + +{{% /experimental %}}` + }} + {{ end }} + {{ with $data.kubernetes }} +

+ {{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }} + This command works with the Kubernetes orchestrator. +

+ {{ end }} + {{ with $data.swarm }} +

+ {{ partialCached "components/badge.html" (dict "color" "blue" "content" "Swarm") "swarm" }} + This command works with the Swarm orchestrator. +

+ {{ end }} + + {{/* Always show YAML long description */}} + {{ with $data.long }} + {{ $heading := dict "level" 2 "text" "Description" }} + {{ partialCached "heading.html" $heading "cli-description" }} + {{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }} + {{ $.Store.Add "headings" $heading }} + {{ range $subHeadings }} + {{ $lvl := strings.Count "#" . }} + {{ $txt := strings.TrimLeft "# " . }} + {{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }} + {{ end }} + {{ . | $.RenderString (dict "display" "block") }} + {{ end }} + + {{ with $data.options }} + {{ $opts := where . "hidden" false }} + {{ with $opts }} + {{ $heading := dict "level" 2 "text" "Options" }} + {{ partialCached "heading.html" $heading "cli-options" }} + {{ $.Store.Add "headings" $heading }} +
+ + + + + + + + + + {{ range . }} + + {{ $short := .shorthand }} + {{ $long := .option }} + + {{ $skipDefault := `[],map[],false,0,0s,default,'',""` }} + + + + {{ end }} + +
OptionDefaultDescription
+ {{ with .details_url }} + + {{ with $short }}-{{ . }}, {{end}}--{{ $long }} + + {{ else }} + {{ with $short }}-{{ . }}, {{end}}--{{ $long }} + {{ end }} + + {{ with .default_value }} + {{ cond (in $skipDefault .) "" (printf "%s" . | safeHTML) }} + {{ end }} + + {{ with .min_api_version }} + {{ partialCached "components/badge.html" (dict "color" "blue" "content" (printf "API %s+" .)) "api" . }} + {{ end }} + {{ with .deprecated }} + {{ partialCached "components/badge.html" (dict "color" "red" "content" "Deprecated") "deprecated" }} + {{ end }} + {{ with .experimental }} + {{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (daemon)") "exp" }} + {{ end }} + {{ with .experimentalcli }} + {{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (CLI)") "exp-cli" }} + {{ end }} + {{ with .kubernetes }} + {{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }} + {{ end }} + {{ with .swarm }} + {{ partialCached "components/badge.html" (dict "color" "blue" "content" "Swarm") "swarm" }} + {{ end }} + {{ if .description }} + {{/* replace newlines in long desc with break tags */}} + {{ markdownify (strings.Replace .description "\n" "
") }} + {{ end }} +
+
+ {{ end }} + {{ end }} + + {{ if $useMarkdownContent }} + {{/* Use markdown content after MARKER_GEN_END */}} + {{ $subHeadings := (strings.FindRE `(?m:#{2,4} .*)` $markdownContent) }} + {{ range $subHeadings }} + {{ $lvl := strings.Count "#" . }} + {{ $txt := strings.TrimLeft "# " . }} + {{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }} + {{ end }} + {{ $markdownContent | $.RenderString (dict "display" "block") }} + {{ else }} + {{/* Fallback to YAML examples if no markdown content after marker */}} + {{ with $data.examples }} + {{ $heading := dict "level" 2 "text" "Examples" }} + {{ partialCached "heading.html" $heading "cli-examples" }} + {{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }} + {{ $.Store.Add "headings" $heading }} + {{ range $subHeadings }} + {{ $lvl := strings.Count "#" . }} + {{ $txt := strings.TrimLeft "# " . }} + {{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }} + {{ end }} + {{ $.RenderString (dict "display" "block") . }} + {{ end }} + {{ end }} + + {{ if eq .Kind "section" }} + {{ $heading := dict "level" 2 "text" "Subcommands" }} + {{ partialCached "heading.html" $heading "cli-subcommands" }} + {{ $.Store.Add "headings" $heading }} + + + + + + + + + {{ range .Pages }} + {{- if and .Params.datafolder .Params.datafile }} + + + {{- end }} + {{ end }} + +
CommandDescription
{{ .Title }} + {{ $data := index (index site.Data .Params.datafolder) .Params.datafile }} + {{ $data.short }} +
+ {{ end }} +
+ + + +{{ end }} \ No newline at end of file