YAML: add "generated file" comment, and set custom default "source" for man pages#76
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds explicit “generated file” markers to YAML outputs and introduces a default Source value for generated man pages when none is provided, improving traceability of generated documentation artifacts.
Changes:
- Prepend a “Code generated by github.com/docker/cli-docs-tool; DO NOT EDIT.” comment to generated YAML files.
- Add a package-level
generatedFileconstant to centralize the generated-file marker text. - Set a default
manHeader.Sourcestring for manpage generation whenSourceis empty.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| fixtures/docker_buildx_stop.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx_install.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx_imagetools_create.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx_imagetools.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx_dial-stdio.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx_build.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_buildx.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker_attach.yaml | Adds generated-file comment header to YAML fixture. |
| fixtures/docker.yaml | Adds generated-file comment header to YAML fixture. |
| clidocstool_yaml.go | Prepends generated-file comment to YAML generation output. |
| clidocstool_man.go | Sets a default manpage Source when not provided. |
| clidocstool.go | Introduces generatedFile constant used for generated-file markers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
thaJeztah
force-pushed
the
add_generated_headers
branch
from
bdab251 to
ae11ddc
Compare
thaJeztah
force-pushed
the
add_generated_headers
branch
from
ae11ddc to
b58a63b
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
clidocstool_yaml.go
Outdated
| } | ||
| return c.genYamlTreeCustom(cmd, emptyStr) | ||
| return c.genYamlTreeCustom(cmd, func(string) string { | ||
| return "# " + generatedFile + "\n\n" |
There was a problem hiding this comment.
I wouldn't leave an empty line in there, but maybe that's just me
| return "# " + generatedFile + "\n\n" | |
| return "# " + generatedFile + "\n" |
There was a problem hiding this comment.
Yup, works for me; I thought the extra line would give a bit more separation between "preamble" and the actual document, but either way works for me! Let me update.
In general, I'm not sure if there's editors currently looking for these comments in YAML; I know editors do it for go files (and kinda why I picked this specific format, which is documented).
For the docker/docs repo, we probably should have something similar to https://github.com/moby/moby/blob/785ae9a0f934e1105ce8021179d539c1c5660bb7/daemon/libnetwork/internal/nftables/testdata/.gitattributes#L1
*.golden linguist-generated=true
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Cobra sets a default Source if none is set;
header.Source = "Auto generated by spf13/cobra"
Set our own Source for the man pages we generate.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
thaJeztah
force-pushed
the
add_generated_headers
branch
from
b58a63b to
8fa1c1a
Compare
|
@crazy-max ptal 🤗 |
|
@thaJeztah could you do a release of this too? |
3 participants
No description provided.