Skip to content

Commit 5489615

Browse files
craig-osterhoutcraig-osterhout
authored
scout: fix watch docs (#23506)
<!--Delete sections as needed --> ## 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: docker/scout-cli-plugin#713 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Editorial review Signed-off-by: Craig Osterhout <[email protected]>
1 parent e534111 commit 5489615

File tree

2 files changed

+289
-1
lines changed

2 files changed

+289
-1
lines changed

‎content/reference/cli/docker/scout/watch.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
22
datafolder: scout-cli
33
datafile: docker_scout_watch
4+
markdownfile: scout_watch.md
45
aliases:
56
- /engine/reference/commandline/scout_watch
67
title: docker scout watch
7-
layout: cli
8+
layout: scout-cli
89
---
910

1011
<!--

‎layouts/_default/scout-cli.html‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
{{ define "main" }}
2+
{{ $data := "" }}
3+
{{ if .Params.datafolder }}
4+
{{ $data = index (index site.Data .Params.datafolder) .Params.datafile }}
5+
{{ else }}
6+
{{ $data = index site.Data .Params.datafile }}
7+
{{ end }}
8+
9+
{{ $markdownFile := "" }}
10+
{{ if .Params.markdownfile }}
11+
{{ $markdownFile = .Params.markdownfile }}
12+
{{ end }}
13+
14+
{{/* Check if we should use markdown content early */}}
15+
{{ $useMarkdownContent := false }}
16+
{{ $markdownContent := "" }}
17+
{{ if $markdownFile }}
18+
{{ $markdownPath := printf "_vendor/github.com/docker/scout-cli/docs/%s" $markdownFile }}
19+
{{ $fullMarkdownContent := readFile $markdownPath }}
20+
{{ if $fullMarkdownContent }}
21+
{{ $parts := split $fullMarkdownContent "<!---MARKER_GEN_END-->" }}
22+
{{ if gt (len $parts) 1 }}
23+
{{ $contentAfterMarker := index $parts 1 }}
24+
{{ $contentAfterMarker = strings.TrimLeft "\n" $contentAfterMarker }}
25+
{{ if gt (len (strings.TrimSpace $contentAfterMarker)) 0 }}
26+
{{ $useMarkdownContent = true }}
27+
{{/* Skip markdown description section if it exists, use only content after it */}}
28+
{{ if strings.Contains $contentAfterMarker "## Examples" }}
29+
{{/* If there's an Examples section, split on it and use everything from Examples onward */}}
30+
{{ $examplesParts := split $contentAfterMarker "## Examples" }}
31+
{{ if gt (len $examplesParts) 1 }}
32+
{{ $markdownContent = printf "## Examples%s" (index $examplesParts 1) }}
33+
{{ else }}
34+
{{ $markdownContent = $contentAfterMarker }}
35+
{{ end }}
36+
{{ else }}
37+
{{/* No Examples section, use all content but skip Description if present */}}
38+
{{ if strings.HasPrefix (strings.TrimSpace $contentAfterMarker) "## Description" }}
39+
{{/* Very simple approach: just use empty content if it starts with Description */}}
40+
{{ $markdownContent = "" }}
41+
{{ else }}
42+
{{ $markdownContent = $contentAfterMarker }}
43+
{{ end }}
44+
{{ end }}
45+
{{ end }}
46+
{{ end }}
47+
{{ end }}
48+
{{ end }}
49+
50+
{{ .Store.Set "headings" slice }}
51+
{{ .Store.Set "subheadings" slice }}
52+
<div class="flex w-full">
53+
<article class="prose min-w-0 flex-[2_2_0%] max-w-4xl dark:prose-invert">
54+
{{ partial "breadcrumbs.html" . }}
55+
<h1>{{ .Title }}</h1>
56+
<div class="overflow-x-auto">
57+
<table>
58+
<tbody>
59+
{{ with $data.short }}
60+
<tr>
61+
<th class="text-left w-32">Description</th>
62+
<td>{{ . }}</td>
63+
</tr>
64+
{{ end }}
65+
{{ with $data.usage }}
66+
<tr>
67+
<th class="text-left w-32">Usage</th>
68+
<td><code>{{ . }}</code></td>
69+
</tr>
70+
{{ end }}
71+
{{ with $data.aliases }}
72+
{{ $aliases := strings.Replace . (fmt.Printf "%s, " page.Title) "" }}
73+
<tr>
74+
<th class="text-left w-32 flex items-center gap-2">
75+
<span>Aliases</span>
76+
{{ partialCached "tooltip.html" "An alias is a short or memorable alternative for a longer command." "cli-alias" }}
77+
</th>
78+
<td>
79+
<div class="flex gap-3">
80+
{{ range (strings.Split $aliases ", ") }}
81+
<code>{{ . }}</code>
82+
{{ end }}
83+
</div>
84+
</td>
85+
</tr>
86+
{{ end }}
87+
</tbody>
88+
</table>
89+
</div>
90+
{{ .Content }}
91+
{{ if $data.deprecated }}
92+
{{ markdownify `
93+
> [!WARNING]
94+
> This command is deprecated
95+
>
96+
> It may be removed in a future Docker version. For more information, see the
97+
> [Docker roadmap](https://github.com/docker/roadmap/issues/209)`
98+
}}
99+
{{ end }}
100+
{{ if or $data.experimental $data.experimentalcli }}
101+
{{ markdownify `
102+
{{% experimental %}}
103+
104+
**This command is experimental.**
105+
106+
Experimental features are intended for testing and feedback as their
107+
functionality or design may change between releases without warning or
108+
can be removed entirely in a future release.
109+
110+
{{% /experimental %}}`
111+
}}
112+
{{ end }}
113+
{{ with $data.kubernetes }}
114+
<p>
115+
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }}
116+
This command works with the Kubernetes orchestrator.
117+
</p>
118+
{{ end }}
119+
{{ with $data.swarm }}
120+
<p>
121+
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Swarm") "swarm" }}
122+
This command works with the Swarm orchestrator.
123+
</p>
124+
{{ end }}
125+
126+
{{/* Always show YAML long description */}}
127+
{{ with $data.long }}
128+
{{ $heading := dict "level" 2 "text" "Description" }}
129+
{{ partialCached "heading.html" $heading "cli-description" }}
130+
{{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }}
131+
{{ $.Store.Add "headings" $heading }}
132+
{{ range $subHeadings }}
133+
{{ $lvl := strings.Count "#" . }}
134+
{{ $txt := strings.TrimLeft "# " . }}
135+
{{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }}
136+
{{ end }}
137+
{{ . | $.RenderString (dict "display" "block") }}
138+
{{ end }}
139+
140+
{{ with $data.options }}
141+
{{ $opts := where . "hidden" false }}
142+
{{ with $opts }}
143+
{{ $heading := dict "level" 2 "text" "Options" }}
144+
{{ partialCached "heading.html" $heading "cli-options" }}
145+
{{ $.Store.Add "headings" $heading }}
146+
<div class="overflow-x-auto">
147+
<table>
148+
<thead class="bg-gray-100 dark:bg-gray-800">
149+
<tr>
150+
<th class="p-2">Option</th>
151+
<th class="p-2">Default</th>
152+
<th class="p-2">Description</th>
153+
</tr>
154+
</thead>
155+
<tbody>
156+
{{ range . }}
157+
<tr class="p-2">
158+
{{ $short := .shorthand }}
159+
{{ $long := .option }}
160+
<td>
161+
{{ with .details_url }}
162+
<a class="link" href="{{ . }}">
163+
<code>{{ with $short }}-{{ . }}, {{end}}--{{ $long }}</code>
164+
</a>
165+
{{ else }}
166+
<code>{{ with $short }}-{{ . }}, {{end}}--{{ $long }}</code>
167+
{{ end }}
168+
</td>
169+
{{ $skipDefault := `[],map[],false,0,0s,default,'',""` }}
170+
<td>
171+
{{ with .default_value }}
172+
{{ cond (in $skipDefault .) "" (printf "<code>%s</code>" . | safeHTML) }}
173+
{{ end }}
174+
</td>
175+
<td>
176+
{{ with .min_api_version }}
177+
{{ partialCached "components/badge.html" (dict "color" "blue" "content" (printf "API %s+" .)) "api" . }}
178+
{{ end }}
179+
{{ with .deprecated }}
180+
{{ partialCached "components/badge.html" (dict "color" "red" "content" "Deprecated") "deprecated" }}
181+
{{ end }}
182+
{{ with .experimental }}
183+
{{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (daemon)") "exp" }}
184+
{{ end }}
185+
{{ with .experimentalcli }}
186+
{{ partialCached "components/badge.html" (dict "color" "amber" "content" "experimental (CLI)") "exp-cli" }}
187+
{{ end }}
188+
{{ with .kubernetes }}
189+
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }}
190+
{{ end }}
191+
{{ with .swarm }}
192+
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Swarm") "swarm" }}
193+
{{ end }}
194+
{{ if .description }}
195+
{{/* replace newlines in long desc with break tags */}}
196+
{{ markdownify (strings.Replace .description "\n" "<br>") }}
197+
{{ end }}
198+
</td>
199+
</tr>
200+
{{ end }}
201+
</tbody>
202+
</table>
203+
</div>
204+
{{ end }}
205+
{{ end }}
206+
207+
{{ if $useMarkdownContent }}
208+
{{/* Use markdown content after MARKER_GEN_END */}}
209+
{{ $subHeadings := (strings.FindRE `(?m:#{2,4} .*)` $markdownContent) }}
210+
{{ range $subHeadings }}
211+
{{ $lvl := strings.Count "#" . }}
212+
{{ $txt := strings.TrimLeft "# " . }}
213+
{{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }}
214+
{{ end }}
215+
{{ $markdownContent | $.RenderString (dict "display" "block") }}
216+
{{ else }}
217+
{{/* Fallback to YAML examples if no markdown content after marker */}}
218+
{{ with $data.examples }}
219+
{{ $heading := dict "level" 2 "text" "Examples" }}
220+
{{ partialCached "heading.html" $heading "cli-examples" }}
221+
{{ $subHeadings := (strings.FindRE `(?m:#{3,4} .*)` .) }}
222+
{{ $.Store.Add "headings" $heading }}
223+
{{ range $subHeadings }}
224+
{{ $lvl := strings.Count "#" . }}
225+
{{ $txt := strings.TrimLeft "# " . }}
226+
{{ $.Store.Add "headings" (dict "level" $lvl "text" $txt) }}
227+
{{ end }}
228+
{{ $.RenderString (dict "display" "block") . }}
229+
{{ end }}
230+
{{ end }}
231+
232+
{{ if eq .Kind "section" }}
233+
{{ $heading := dict "level" 2 "text" "Subcommands" }}
234+
{{ partialCached "heading.html" $heading "cli-subcommands" }}
235+
{{ $.Store.Add "headings" $heading }}
236+
<table>
237+
<thead>
238+
<tr>
239+
<th class="text-left">Command</th>
240+
<th class="text-left">Description</th>
241+
</tr>
242+
</thead>
243+
<tbody>
244+
{{ range .Pages }}
245+
{{- if and .Params.datafolder .Params.datafile }}
246+
<tr>
247+
<td class="text-left"><a class="link" href="{{ .Permalink }}"><code>{{ .Title }}</code></a></th>
248+
{{ $data := index (index site.Data .Params.datafolder) .Params.datafile }}
249+
<td class="text-left">{{ $data.short }}</th>
250+
</tr>
251+
{{- end }}
252+
{{ end }}
253+
</tbody>
254+
</table>
255+
{{ end }}
256+
</article>
257+
258+
<div class="hidden flex-1 min-w-52 lg:block">
259+
<aside
260+
class="sticky top-16 h-[calc(100vh-64px)] min-w-52 space-y-4 overflow-y-auto py-4 w-full"
261+
>
262+
<div id="TableOfContents">
263+
<div class="text-lg pb-2">{{ T "tableOfContents" }}</div>
264+
<nav class="toc">
265+
<ul>
266+
{{ range (.Store.Get "headings") }}
267+
{{/* add left padding depending on level (pl-2, pl-3, pl-4) */}}
268+
{{ $slice := strings.Split .text "{#" }}
269+
{{ $text := index $slice 0 }}
270+
{{ $anchor := index $slice 1 | strings.TrimRight "}" }}
271+
<li{{ with .level }} class="pl-{{ . }}"{{ end }}>
272+
<a
273+
{{ if $anchor }}
274+
href="#{{ $anchor }}"
275+
{{ else }}
276+
href="#{{ $text | anchorize }}"
277+
{{ end }}
278+
>{{ markdownify $text }}</a>
279+
</li>
280+
{{ end }}
281+
</ul>
282+
</nav>
283+
</div>
284+
</aside>
285+
</div>
286+
287+
{{ end }}

0 commit comments

Comments
 (0)