Add syntax and examples to the description text of some complex options#3417
Open
gibson042 wants to merge 6 commits into
Open
Add syntax and examples to the description text of some complex options#3417gibson042 wants to merge 6 commits into
gibson042 wants to merge 6 commits into
Conversation
gibson042
commented
Feb 1, 2022
| @@ -14,122 +14,113 @@ Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] | |||
| Create a new container | |||
|
|
|||
| Options: | |||
Author
There was a problem hiding this comment.
These changes are best viewed while ignoring whitespace. There are some actual changes, but only because docs/reference/commandline/ apparently contains stale content.
| "type=volume,target=/mnt/persistent" or | ||
| "type=bind,ro,src=/var/run/docker.sock,dst=/run/host-docker.sock") | ||
| --name string Assign a name to the container | ||
| --network network Connect a container to a network |
Author
There was a problem hiding this comment.
Should the list of special --network values be documented by the actual description in cli/command/container/opts.go?
| --shm-size bytes Size of /dev/shm | ||
| The format is `<number><unit>`. `number` must be greater than `0`. | ||
| Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), | ||
| or `g` (gigabytes). If you omit the unit, the system uses bytes. |
Author
There was a problem hiding this comment.
Is this ability to specify --shm-size units accurate, and if so should it be documented by the actual description in cli/command/container/opts.go?
| -u, --user string Username or UID (format: <name|uid>[:<group|gid>]) | ||
| --userns string User namespace to use | ||
| 'host': Use the Docker host user namespace | ||
| '': Use the Docker daemon user namespace specified by `--userns-remap` option. |
Author
There was a problem hiding this comment.
Should the list of special --userns values be documented by the actual description in cli/command/container/opts.go?
| --userns string User namespace to use | ||
| --uts string UTS namespace to use | ||
| -v, --volume list Bind mount a volume (format: [<volume name|absolute | ||
| host path>:]<absolute container path>[:<options>]) |
Author
There was a problem hiding this comment.
Should the description of --volume in cli/command/container/opts.go include the list of options?
Author
|
I'm also not clear on how (if at all) contrib/completion/ files should be updated. |
gibson042
commented
Feb 1, 2022
| --entrypoint string Overwrite the default ENTRYPOINT of the image | ||
| -e, --env list Set environment variables | ||
| --env-file list Read in a file of environment variables | ||
| --expose list Expose a port or a range of ports |
Author
There was a problem hiding this comment.
"range of ports" seems sufficiently special to merit more text, perhaps something like this?
--expose list Expose a port or a range of ports (e.g., "80,443,2379-2380")
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
```sh
for cmd in create run; do
doc="docs/reference/commandline/$cmd.md"
tmp="$(mktemp)"
awk -v cmd="$cmd" '
# Replace the contents of the first markdown block
# with output from docker help (omitting leading blank lines).
/^```markdown/ && !replaced {
# Print the block start.
print;
# Insert `docker help` output.
while(("./build/docker help " cmd | getline)>0) {
if(NF>0) trimmed=1;
if(trimmed) print;
}
# Advance to the block end.
while(getline>0 && $0!="```");
replaced++;
}
{ print }
' "$doc" >"$tmp" && \
mv "$tmp" "$doc"
done
```
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
```sh
for cmd in build create run update; do
doc="docs/reference/commandline/$cmd.md"
tmp="$(mktemp)"
awk -v cmd="$cmd" '
# Replace the contents of the first markdown block
# with output from docker help (omitting leading blank lines).
/^```markdown/ && !replaced {
# Print the block start.
print;
# Insert `docker help` output.
while(("./build/docker help " cmd | getline)>0) {
if(NF>0) trimmed=1;
if(trimmed) print;
}
# Advance to the block end.
while(getline>0 && $0!="```");
replaced++;
}
{ print }
' "$doc" >"$tmp" && \
mv "$tmp" "$doc"
done
```
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
Signed-off-by: Richard Gibson <richard.gibson@gmail.com>
gibson042
force-pushed
the
2022-01-improve-cli-option-documentation
branch
from
78648be to
3f807a4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
- What I did
--publishand--volume, and values for--restart.--mountlike those at https://docs.docker.com/engine/reference/commandline/run/#add-bind-mounts-or-volumes-using-the---mount-flag .- How I did it
Updated
flagsdescription arguments in cli/command/ files.- How to verify it
Build the
dockerexecutable and invoke it withhelp runorhelp create.- Description for the changelog
Add syntax and examples to the description text of some complex options.
- A picture of a cute animal (not mandatory but encouraged)
https://twitter.com/EveryBat/status/1229018840308125696