Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2390 from thaJeztah/fix_yamldocs 

Fix yamldocs generator to accomodate nested subcommands
This commit is contained in:
Silvin Lubecki 2020-03-17 16:49:23 +01:00 committed by GitHub
parent ef2f64abbd f912deeec7
commit 8e1030c2f8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 284 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/reference/commandline/events.md
View File

@ -207,7 +207,7 @@ format. Go's [text/template](http://golang.org/pkg/text/template/) package
describes all the details of the format.
If a format is set to `{{json .}}`, the events are streamed as valid JSON
Lines. For information about JSON Lines, please refer to http://jsonlines.org/ .
Lines. For information about JSON Lines, please refer to http://jsonlines.org/.
## Examples
@ -410,12 +410,12 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299
#### Format as JSON
```none
$ docker events --format '{{json .}}'
```bash
$ docker events --format '{{json .}}'
{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
```

2
docs/reference/commandline/login.md
View File

@ -32,6 +32,8 @@ Options:
Login to a registry.
## Examples
### Login to a self-hosted registry
If you want to login to a self-hosted registry you can specify this by

50
docs/reference/commandline/manifest.md
View File

@ -43,8 +43,8 @@ more (ideally more than one) image names. It can then be used in the same way as
an image name in `docker pull` and `docker run` commands, for example.
Ideally a manifest list is created from images that are identical in function for
different os/arch combinations. For this reason, manifest lists are often referred to as
"multi-arch images". However, a user could create a manifest list that points
different os/arch combinations. For this reason, manifest lists are often referred
to as "multi-arch images". However, a user could create a manifest list that points
to two images -- one for windows on amd64, and one for darwin on amd64.
### manifest inspect
@ -76,6 +76,7 @@ Options:
```
### manifest annotate
```bash
Usage: docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST
@ -91,6 +92,7 @@ Options:
```
### manifest push
```bash
Usage: docker manifest push [OPTIONS] MANIFEST_LIST
@ -104,7 +106,16 @@ Options:
### Working with insecure registries
The manifest command interacts solely with a Docker registry. Because of this, it has no way to query the engine for the list of allowed insecure registries. To allow the CLI to interact with an insecure registry, some `docker manifest` commands have an `--insecure` flag. For each transaction, such as a `create`, which queries a registry, the `--insecure` flag must be specified. This flag tells the CLI that this registry call may ignore security concerns like missing or self-signed certificates. Likewise, on a `manifest push` to an insecure registry, the `--insecure` flag must be specified. If this is not used with an insecure registry, the manifest command fails to find a registry that meets the default requirements.
The manifest command interacts solely with a Docker registry. Because of this,
it has no way to query the engine for the list of allowed insecure registries.
To allow the CLI to interact with an insecure registry, some `docker manifest`
commands have an `--insecure` flag. For each transaction, such as a `create`,
which queries a registry, the `--insecure` flag must be specified. This flag
tells the CLI that this registry call may ignore security concerns like missing
or self-signed certificates. Likewise, on a `manifest push` to an insecure
registry, the `--insecure` flag must be specified. If this is not used with an
insecure registry, the manifest command fails to find a registry that meets the
default requirements.
## Examples
@ -136,7 +147,7 @@ The `docker manifest inspect` command takes an optional `--verbose` flag
that gives you the image's name (Ref), and architecture and os (Platform).
Just as with other docker commands that take image names, you can refer to an image with or
without a tag, or by digest (e.g. hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f).
without a tag, or by digest (e.g. `hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f`).
Here is an example of inspecting an image's manifest with the `--verbose` flag:
@ -170,17 +181,19 @@ $ docker manifest inspect --verbose hello-world
### Create and push a manifest list
To create a manifest list, you first `create` the manifest list locally by specifying the constituent images you would
like to have included in your manifest list. Keep in mind that this is pushed to a registry, so if you want to push
to a registry other than the docker registry, you need to create your manifest list with the registry name or IP and port.
To create a manifest list, you first `create` the manifest list locally by
specifying the constituent images you would like to have included in your
manifest list. Keep in mind that this is pushed to a registry, so if you want to
push to a registry other than the docker registry, you need to create your
manifest list with the registry name or IP and port.
This is similar to tagging an image and pushing it to a foreign registry.
After you have created your local copy of the manifest list, you may optionally
`annotate` it. Annotations allowed are the architecture and operating system (overriding the image's current values),
os features, and an architecture variant.
`annotate` it. Annotations allowed are the architecture and operating system
(overriding the image's current values), os features, and an architecture variant.
Finally, you need to `push` your manifest list to the desired registry. Below are descriptions of these three commands,
and an example putting them all together.
Finally, you need to `push` your manifest list to the desired registry. Below are
descriptions of these three commands, and an example putting them all together.
```bash
$ docker manifest create 45.55.81.106:5000/coolapp:v1 \
@ -188,6 +201,7 @@ $ docker manifest create 45.55.81.106:5000/coolapp:v1 \
45.55.81.106:5000/coolapp-arm-linux:v1 \
45.55.81.106:5000/coolapp-amd64-linux:v1 \
45.55.81.106:5000/coolapp-amd64-windows:v1
Created manifest list 45.55.81.106:5000/coolapp:v1
```
@ -255,9 +269,10 @@ $ docker manifest inspect coolapp:v1
### Push to an insecure registry
Here is an example of creating and pushing a manifest list using a known insecure registry.
Here is an example of creating and pushing a manifest list using a known
insecure registry.
```
```bash
$ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1.0 \
myprivateregistry.mycompany.com/repo/image-linux-ppc64le:1.0 \
myprivateregistry.mycompany.com/repo/image-linux-s390x:1.0 \
@ -265,10 +280,13 @@ $ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1
myprivateregistry.mycompany.com/repo/image-linux-armhf:1.0 \
myprivateregistry.mycompany.com/repo/image-windows-amd64:1.0 \
myprivateregistry.mycompany.com/repo/image-linux-amd64:1.0
```
```
$ docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag
```
Note that the `--insecure` flag is not required to annotate a manifest list, since annotations are to a locally-stored copy of a manifest list. You may also skip the `--insecure` flag if you are performing a `docker manifest inspect` on a locally-stored manifest list. Be sure to keep in mind that locally-stored manifest lists are never used by the engine on a `docker pull`.
> **Note**: the `--insecure` flag is not required to annotate a manifest list,
> since annotations are to a locally-stored copy of a manifest list. You may also
> skip the `--insecure` flag if you are performing a `docker manifest inspect`
> on a locally-stored manifest list. Be sure to keep in mind that locally-stored
> manifest lists are never used by the engine on a `docker pull`.

17
docs/reference/commandline/node_inspect.md
View File

@ -42,11 +42,13 @@ details of the format.
### Inspect a node
```none
```bash
$ docker node inspect swarm-manager
```
```json
[
{
{
"ID": "e216jshn25ckzbvmwlnh5jr3g",
"Version": {
"Index": 10
@ -111,18 +113,23 @@ $ docker node inspect swarm-manager
"Reachability": "reachable",
"Addr": "168.0.32.137:2377"
}
}
}
]
```
### Specify an output format
```none
```bash
$ docker node inspect --format '{{ .ManagerStatus.Leader }}' self
false
```
Use `--format=pretty` or the `--pretty` shorthand to pretty-print the output:
```bash
$ docker node inspect --format=pretty self
$ docker node inspect --pretty self
ID: e216jshn25ckzbvmwlnh5jr3g
Hostname: swarm-manager
Joined at: 2017-05-16 22:52:44.9910662 +0000 utc

6
docs/reference/commandline/push.md
View File

@ -38,9 +38,9 @@ image and tag names.
Killing the `docker image push` process, for example by pressing `CTRL-c` while it is
running in a terminal, terminates the push operation.
Progress bars are shown during docker push, which show the uncompressed size. The
actual amount of data that's pushed will be compressed before sending, so the uploaded
size will not be reflected by the progress bar.
Progress bars are shown during docker push, which show the uncompressed size.
The actual amount of data that's pushed will be compressed before sending, so
the uploaded size will not be reflected by the progress bar.
Registry credentials are managed by [docker login](login.md).

12
docs/reference/commandline/swarm_init.md
View File

@ -149,12 +149,12 @@ the port is configured:
```bash
docker info
...
ClusterID: 9vs5ygs0gguyyec4iqf2314c0
Managers: 1
Nodes: 1
Data Path Port: 7777
...
...
ClusterID: 9vs5ygs0gguyyec4iqf2314c0
Managers: 1
Nodes: 1
Data Path Port: 7777
...
```
### `--default-addr-pool`

0
docs/reference/commandline/swarm_join_token.md → docs/reference/commandline/swarm_join-token.md
View File

0
docs/reference/commandline/swarm_unlock_key.md → docs/reference/commandline/swarm_unlock-key.md
View File

2
docs/reference/commandline/trust_key_generate.md
View File

@ -43,7 +43,6 @@ Repeat passphrase for new alice key with ID 17acf3c:
Successfully generated and loaded private key. Corresponding public key available: alice.pub
$ ls
alice.pub
```
The private signing key is encrypted by the passphrase and loaded into the docker trust keystore.
@ -63,5 +62,4 @@ Repeat passphrase for new alice key with ID 17acf3c:
Successfully generated and loaded private key. Corresponding public key available: alice.pub
$ ls /foo
alice.pub
```

9
docs/reference/commandline/trust_key_load.md
View File

@ -27,7 +27,9 @@ Options:
## Description
`docker trust key load` adds private keys to the local docker trust keystore. To add a signer to a repository use `docker trust signer add`.
`docker trust key load` adds private keys to the local docker trust keystore.
To add a signer to a repository use `docker trust signer add`.
## Examples
@ -42,9 +44,9 @@ Loading key from "alice.pem"...
Enter passphrase for new signer key with ID f8097df:
Repeat passphrase for new signer key with ID f8097df:
Successfully imported key from alice.pem
```
to specify a name use the `--name` flag
To specify a name use the `--name` flag:
```bash
$ docker trust key load --name alice-key alice.pem
@ -53,5 +55,4 @@ Loading key from "alice.pem"...
Enter passphrase for new alice-key key with ID f8097df:
Repeat passphrase for new alice-key key with ID f8097df:
Successfully imported key from alice.pem
```

3
docs/reference/commandline/trust_sign.md
View File

@ -65,7 +65,7 @@ Enter passphrase for repository key with ID 36d4c36:
Successfully signed docker.io/example/trust-demo:v2
```
`docker trust view` lists the new signature:
Use `docker trust view` to list the new signature:
```bash
$ docker trust view example/trust-demo
@ -181,4 +181,3 @@ Administrative keys for example/trust-demo:
Repository Key: 731396b65eac3ef5ec01406801bdfb70feb40c17808d2222427c18046eb63beb
Root Key: 70d174714bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103
```

11
docs/reference/commandline/trust_signer_add.md
View File

@ -57,7 +57,7 @@ Add `alice` with `docker trust signer add`:
$ docker trust signer add alice example/trust-demo --key alice.crt
Adding signer "alice" to example/trust-demo...
Enter passphrase for repository key with ID 642692c:
Successfully added signer: alice to example/trust-demo
Successfully added signer: alice to example/trust-demo
```
`docker trust view` now lists `alice` as a valid signer:
@ -92,11 +92,11 @@ No signatures or cannot access example/trust-demo
$ docker trust signer add alice example/trust-demo --key alice.crt
Initializing signed repository for example/trust-demo...
Enter passphrase for root key with ID 748121c:
Enter passphrase for new repository key with ID 95b9e55:
Repeat passphrase for new repository key with ID 95b9e55:
Successfully initialized "example/trust-demo"
Enter passphrase for new repository key with ID 95b9e55:
Repeat passphrase for new repository key with ID 95b9e55:
Successfully initialized "example/trust-demo"
Adding signer "alice" to example/trust-demo...
Adding signer "alice" to example/trust-demo...
Successfully added signer: alice to example/trust-demo
```
@ -120,7 +120,6 @@ Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103
## Add a signer to multiple repos
To add a signer, `alice`, to multiple repositories:
```bash
$ docker trust view example/trust-demo
SIGNED TAG DIGEST SIGNERS

21
docs/reference/commandline/trust_signer_remove.md
View File

@ -34,7 +34,6 @@ Options:
### Remove a signer from a repo
To remove an existing signer, `alice`, from this repository:
```bash
$ docker trust view example/trust-demo
@ -56,10 +55,10 @@ Remove `alice` with `docker trust signer remove`:
```bash
$ docker trust signer remove alice example/trust-demo
Removing signer "alice" from image example/trust-demo...
Enter passphrase for repository key with ID 642692c:
Successfully removed alice from example/trust-demo
Removing signer "alice" from image example/trust-demo...
Enter passphrase for repository key with ID 642692c:
Successfully removed alice from example/trust-demo
```
`docker trust view` now does not list `alice` as a valid signer:
@ -99,6 +98,7 @@ Administrative keys for example/trust-demo:
Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```
```bash
$ docker trust view example/trust-demo2
SIGNED TAG DIGEST SIGNERS
@ -114,10 +114,12 @@ Administrative keys for example/trust-demo2:
Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```
Remove `alice` from both images with a single `docker trust signer remove` command:
```bash
$ docker trust signer remove alice example/trust-demo example/trust-demo2
Removing signer "alice" from image example/trust-demo...
Enter passphrase for repository key with ID 95b9e55:
Successfully removed alice from example/trust-demo
@ -126,7 +128,10 @@ Removing signer "alice" from image example/trust-demo2...
Enter passphrase for repository key with ID ece554f:
Successfully removed alice from example/trust-demo2
```
`docker trust view` no longer lists `alice` as a valid signer of either `example/trust-demo` or `example/trust-demo2`:
Run `docker trust view` to confirm that `alice` is no longer listed as a valid
signer of either `example/trust-demo` or `example/trust-demo2`:
```bash
$ docker trust view example/trust-demo
SIGNED TAG DIGEST SIGNERS
@ -141,6 +146,7 @@ Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```
```bash
$ docker trust view example/trust-demo2
SIGNED TAG DIGEST SIGNERS
@ -156,10 +162,13 @@ Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d926
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```
`docker trust signer remove` removes signers to repositories on a best effort basis, so it will continue to remove the signer from subsequent repositories if one attempt fails:
`docker trust signer remove` removes signers to repositories on a best effort
basis, so it will continue to remove the signer from subsequent repositories if
one attempt fails:
```bash
$ docker trust signer remove alice example/unauthorized example/authorized
Removing signer "alice" from image example/unauthorized...
No signer alice for image example/unauthorized

41
docs/yaml/generate.go
View File

@ -25,6 +25,7 @@ func generateCliYaml(opts *options) error {
commands.AddCommands(cmd, dockerCli)
disableFlagsInUseLine(cmd)
source := filepath.Join(opts.source, descriptionSourcePath)
fmt.Println("Markdown source:", source)
if err := loadLongDescription(cmd, source); err != nil {
return err
}
@ -50,23 +51,29 @@ func visitAll(root *cobra.Command, fn func(*cobra.Command)) {
fn(root)
}
func loadLongDescription(cmd *cobra.Command, path ...string) error {
for _, cmd := range cmd.Commands() {
if cmd.Name() == "" {
continue
}
fullpath := filepath.Join(path[0], strings.Join(append(path[1:], cmd.Name()), "_")+".md")
func loadLongDescription(parentCmd *cobra.Command, path string) error {
for _, cmd := range parentCmd.Commands() {
if cmd.HasSubCommands() {
loadLongDescription(cmd, path[0], cmd.Name())
if err := loadLongDescription(cmd, path); err != nil {
return err
}
if _, err := os.Stat(fullpath); err != nil {
log.Printf("WARN: %s does not exist, skipping\n", fullpath)
}
name := cmd.CommandPath()
log.Println("INFO: Generating docs for", name)
if i := strings.Index(name, " "); i >= 0 {
// remove root command / binary name
name = name[i+1:]
}
if name == "" {
continue
}
mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
fullPath := filepath.Join(path, mdFile)
content, err := ioutil.ReadFile(fullPath)
if os.IsNotExist(err) {
log.Printf("WARN: %s does not exist, skipping\n", mdFile)
continue
}
content, err := ioutil.ReadFile(fullpath)
if err != nil {
return err
}
@ -95,11 +102,11 @@ func parseArgs() (*options, error) {
func main() {
opts, err := parseArgs()
if err != nil {
fmt.Fprintln(os.Stderr, err.Error())
log.Println(err)
}
fmt.Printf("Project root: %s\n", opts.source)
fmt.Printf("Generating yaml files into %s\n", opts.target)
fmt.Println("Project root: ", opts.source)
fmt.Println("YAML output dir:", opts.target)
if err := generateCliYaml(opts); err != nil {
fmt.Fprintf(os.Stderr, "Failed to generate yaml files: %s\n", err.Error())
log.Println("Failed to generate yaml files:", err)
}
}