mirror of
https://github.com/docker/docs.git
synced 2026-03-27 14:28:47 +07:00
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: https://github.com/docker/scout-cli-plugin/pull/713 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Editorial review Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout
@@ -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
|
||||
---
|
||||
|
||||
<!--
|
||||
|
||||
287
layouts/_default/scout-cli.html
Normal file
287
layouts/_default/scout-cli.html
Normal file
@@ -0,0 +1,287 @@
|
||||
{{ define "main" }}
|
||||
{{ $data := "" }}
|
||||
{{ if .Params.datafolder }}
|
||||
{{ $data = index (index site.Data .Params.datafolder) .Params.datafile }}
|
||||
{{ else }}
|
||||
{{ $data = index site.Data .Params.datafile }}
|
||||
{{ end }}
|
||||
|
||||
{{ $markdownFile := "" }}
|
||||
{{ if .Params.markdownfile }}
|
||||
{{ $markdownFile = .Params.markdownfile }}
|
||||
{{ end }}
|
||||
|
||||
{{/* Check if we should use markdown content early */}}
|
||||
{{ $useMarkdownContent := false }}
|
||||
{{ $markdownContent := "" }}
|
||||
{{ if $markdownFile }}
|
||||
{{ $markdownPath := printf "_vendor/github.com/docker/scout-cli/docs/%s" $markdownFile }}
|
||||
{{ $fullMarkdownContent := readFile $markdownPath }}
|
||||
{{ if $fullMarkdownContent }}
|
||||
{{ $parts := split $fullMarkdownContent "<!---MARKER_GEN_END-->" }}
|
||||
{{ 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 }}
|
||||
<div class="flex w-full">
|
||||
<article class="prose min-w-0 flex-[2_2_0%] max-w-4xl dark:prose-invert">
|
||||
{{ partial "breadcrumbs.html" . }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
<div class="overflow-x-auto">
|
||||
<table>
|
||||
<tbody>
|
||||
{{ with $data.short }}
|
||||
<tr>
|
||||
<th class="text-left w-32">Description</th>
|
||||
<td>{{ . }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
{{ with $data.usage }}
|
||||
<tr>
|
||||
<th class="text-left w-32">Usage</th>
|
||||
<td><code>{{ . }}</code></td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
{{ with $data.aliases }}
|
||||
{{ $aliases := strings.Replace . (fmt.Printf "%s, " page.Title) "" }}
|
||||
<tr>
|
||||
<th class="text-left w-32 flex items-center gap-2">
|
||||
<span>Aliases</span>
|
||||
{{ partialCached "tooltip.html" "An alias is a short or memorable alternative for a longer command." "cli-alias" }}
|
||||
</th>
|
||||
<td>
|
||||
<div class="flex gap-3">
|
||||
{{ range (strings.Split $aliases ", ") }}
|
||||
<code>{{ . }}</code>
|
||||
{{ end }}
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
{{ .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 }}
|
||||
<p>
|
||||
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Kubernetes") "k8s" }}
|
||||
This command works with the Kubernetes orchestrator.
|
||||
</p>
|
||||
{{ end }}
|
||||
{{ with $data.swarm }}
|
||||
<p>
|
||||
{{ partialCached "components/badge.html" (dict "color" "blue" "content" "Swarm") "swarm" }}
|
||||
This command works with the Swarm orchestrator.
|
||||
</p>
|
||||
{{ 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 }}
|
||||
<div class="overflow-x-auto">
|
||||
<table>
|
||||
<thead class="bg-gray-100 dark:bg-gray-800">
|
||||
<tr>
|
||||
<th class="p-2">Option</th>
|
||||
<th class="p-2">Default</th>
|
||||
<th class="p-2">Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range . }}
|
||||
<tr class="p-2">
|
||||
{{ $short := .shorthand }}
|
||||
{{ $long := .option }}
|
||||
<td>
|
||||
{{ with .details_url }}
|
||||
<a class="link" href="{{ . }}">
|
||||
<code>{{ with $short }}-{{ . }}, {{end}}--{{ $long }}</code>
|
||||
</a>
|
||||
{{ else }}
|
||||
<code>{{ with $short }}-{{ . }}, {{end}}--{{ $long }}</code>
|
||||
{{ end }}
|
||||
</td>
|
||||
{{ $skipDefault := `[],map[],false,0,0s,default,'',""` }}
|
||||
<td>
|
||||
{{ with .default_value }}
|
||||
{{ cond (in $skipDefault .) "" (printf "<code>%s</code>" . | safeHTML) }}
|
||||
{{ end }}
|
||||
</td>
|
||||
<td>
|
||||
{{ 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" "<br>") }}
|
||||
{{ end }}
|
||||
</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
{{ 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 }}
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th class="text-left">Command</th>
|
||||
<th class="text-left">Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range .Pages }}
|
||||
{{- if and .Params.datafolder .Params.datafile }}
|
||||
<tr>
|
||||
<td class="text-left"><a class="link" href="{{ .Permalink }}"><code>{{ .Title }}</code></a></th>
|
||||
{{ $data := index (index site.Data .Params.datafolder) .Params.datafile }}
|
||||
<td class="text-left">{{ $data.short }}</th>
|
||||
</tr>
|
||||
{{- end }}
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{ end }}
|
||||
</article>
|
||||
|
||||
<div class="hidden flex-1 min-w-52 lg:block">
|
||||
<aside
|
||||
class="sticky top-16 h-[calc(100vh-64px)] min-w-52 space-y-4 overflow-y-auto py-4 w-full"
|
||||
>
|
||||
<div id="TableOfContents">
|
||||
<div class="text-lg pb-2">{{ T "tableOfContents" }}</div>
|
||||
<nav class="toc">
|
||||
<ul>
|
||||
{{ range (.Store.Get "headings") }}
|
||||
{{/* add left padding depending on level (pl-2, pl-3, pl-4) */}}
|
||||
{{ $slice := strings.Split .text "{#" }}
|
||||
{{ $text := index $slice 0 }}
|
||||
{{ $anchor := index $slice 1 | strings.TrimRight "}" }}
|
||||
<li{{ with .level }} class="pl-{{ . }}"{{ end }}>
|
||||
<a
|
||||
{{ if $anchor }}
|
||||
href="#{{ $anchor }}"
|
||||
{{ else }}
|
||||
href="#{{ $text | anchorize }}"
|
||||
{{ end }}
|
||||
>{{ markdownify $text }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
</nav>
|
||||
</div>
|
||||
</aside>
|
||||
</div>
|
||||
|
||||
{{ end }}
|
||||
Reference in New Issue
Block a user