Man page validation: part 2 of 2

This is the script that runs 'skopeo COMMAND --help' and cross-checks that all the option flags are documented in man pages, and vice-versa (all options listed in man pages appear in COMMAND's --help message). Copied from podman, with changes for skopeo-land (removing the rst checks, and conforming to skopeo conventions). Signed-off-by: Ed Santiago <[email protected]>
containers · Jul 21, 2021 · ae0595c · ae0595c
1 parent b0ebbdd
commit ae0595c
Show file tree

Hide file tree

Showing 15 changed files with 514 additions and 73 deletions.
diff --git a/.cirrus.yml b/.cirrus.yml
@@ -65,6 +65,15 @@ validate_task:
         make validate-local
         make vendor && hack/tree_status.sh
 
+doccheck_task:
+    only_if: $CIRRUS_PR != ''
+    depends_on:
+      - validate
+    container:  *build_container
+    script: |
+      "${GOSRC}/${SCRIPT_BASE}/runner.sh" setup
+      "${SKOPEO_PATH}/${SCRIPT_BASE}/runner.sh" build
+      "${SKOPEO_PATH}/${SCRIPT_BASE}/runner.sh" doccheck
 
 osx_task:
     only_if: &not_docs $CIRRUS_CHANGE_TITLE !=~ '.*CI:DOCS.*'
@@ -185,6 +194,7 @@ success_task:
     # N/B: ALL tasks must be listed here, minus their '_task' suffix.
     depends_on:
         - validate
+        - doccheck
         - osx
         - cross
         - test_skopeo

diff --git a/Makefile b/Makefile
@@ -207,12 +207,17 @@ validate: build-container
 	$(CONTAINER_RUN) make validate-local
 
 # This target is only intended for development, e.g. executing it from an IDE. Use (make test) for CI or pre-release testing.
-test-all-local: validate-local test-unit-local
+test-all-local: validate-local validate-docs test-unit-local
 
 .PHONY: validate-local
 validate-local:
 	hack/make.sh validate-git-marks validate-gofmt validate-lint validate-vet
+
+# This invokes bin/skopeo, hence cannot be run as part of validate-local
+.PHONY: validate-docs
+validate-docs:
 	hack/man-page-checker
+	hack/xref-helpmsgs-manpages
 
 test-unit-local:
 	$(GPGME_ENV) $(GO) test $(MOD_VENDOR) -tags "$(BUILDTAGS)" $$($(GO) list $(MOD_VENDOR) -tags "$(BUILDTAGS)" -e ./... | grep -v '^github\.com/containers/skopeo/\(integration\|vendor/.*\)$$')

diff --git a/contrib/cirrus/runner.sh b/contrib/cirrus/runner.sh
@@ -65,6 +65,10 @@ _run_validate() {
     podmanmake validate-local BUILDTAGS="$BUILDTAGS"
 }
 
+_run_doccheck() {
+    podmanmake validate-docs BUILDTAGS="$BUILDTAGS"
+}
+
 _run_unit() {
     podmanmake test-unit-local BUILDTAGS="$BUILDTAGS"
 }

diff --git a/docs/skopeo-copy.1.md b/docs/skopeo-copy.1.md
@@ -20,7 +20,11 @@ automatically inherit any parts of the source name.
 
 ## OPTIONS
 
-**--all**
+**--additional-tag**=_strings_
+
+Additional tags (supports docker-archive).
+
+**--all**, **-a**
 
 If _source-image_ refers to a list of images, instead of copying just the image which matches the current OS and
 architecture (subject to the use of the global --override-os, --override-arch and --override-variant options), attempt to copy all of
@@ -42,57 +46,119 @@ Path of the authentication file for the source registry. Uses path given by `--a
 
 Path of the authentication file for the destination registry. Uses path given by `--authfile`, if not provided.
 
+**--dest-shared-blob-dir** _directory_
+
+Directory to use to share blobs across OCI repositories.
+
 **--digestfile** _path_
 
 After copying the image, write the digest of the resulting image to the file.
 
-**--format, -f** _manifest-type_ MANIFEST TYPE (oci, v2s1, or v2s2) to use in the destination (default is manifest type of source, with fallbacks)
+**--encrypt-layer** _ints_
+
+*Experimental* the 0-indexed layer indices, with support for negative indexing (e.g. 0 is the first layer, -1 is the last layer)
+
+**--format**, **-f** _manifest-type_
+
+MANIFEST TYPE (oci, v2s1, or v2s2) to use in the destination (default is manifest type of source, with fallbacks)
+
+**--help**, **-h**
+
+Print usage statement
+
+**--quiet**, **-q**
+
+Suppress output information when copying images.
+
+**--remove-signatures**
+
+Do not copy signatures, if any, from _source-image_. Necessary when copying a signed image to a destination which does not support signatures.
+
+**--sign-by**=_key-id_
+
+Add a signature using that key ID for an image name corresponding to _destination-image_
+
+**--src-shared-blob-dir** _directory_
+
+Directory to use to share blobs across OCI repositories.
 
-**--quiet, -q** suppress output information when copying images
+**--encryption-key** _protocol:keyfile_
 
-**--remove-signatures** do not copy signatures, if any, from _source-image_. Necessary when copying a signed image to a destination which does not support signatures.
+Specifies the encryption protocol, which can be JWE (RFC7516), PGP (RFC4880), and PKCS7 (RFC2315) and the key material required for image encryption. For instance, jwe:/path/to/key.pem or pgp:admin@example.com or pkcs7:/path/to/x509-file.
 
-**--sign-by=**_key-id_ add a signature using that key ID for an image name corresponding to _destination-image_
+**--decryption-key** _key[:passphrase]_
 
-**--encryption-key** _protocol:keyfile_ specifies the encryption protocol, which can be JWE (RFC7516), PGP (RFC4880), and PKCS7 (RFC2315) and the key material required for image encryption. For instance, jwe:/path/to/key.pem or pgp:admin@example.com or pkcs7:/path/to/x509-file.
+Key to be used for decryption of images. Key can point to keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.
 
-**--decryption-key** _key[:passphrase]_ to be used for decryption of images. Key can point to keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.
+**--src-creds** _username[:password]_
 
-**--src-creds** _username[:password]_ for accessing the source registry.
+Credentials for accessing the source registry.
 
-**--dest-compress** _bool-value_ Compress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source).
+**--dest-compress** _bool-value_
 
-**--dest-oci-accept-uncompressed-layers** _bool-value_ Allow uncompressed image layers when saving to an OCI image using the 'oci' transport. (default is to compress things that aren't compressed).
+Compress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source).
 
-**--dest-creds** _username[:password]_ for accessing the destination registry.
+**--dest-oci-accept-uncompressed-layers** _bool-value_
 
-**--src-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the source registry or daemon.
+Allow uncompressed image layers when saving to an OCI image using the 'oci' transport. (default is to compress things that aren't compressed).
 
-**--src-no-creds** _bool-value_ Access the registry anonymously.
+**--dest-creds** _username[:password]_
 
-**--src-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container source registry or daemon (defaults to true).
+Credentials for accessing the destination registry.
 
-**--dest-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the destination registry or daemon.
+**--src-cert-dir** _path_
 
-**--dest-no-creds** _bool-value_  Access the registry anonymously.
+Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the source registry or daemon.
 
-**--dest-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container destination registry or daemon (defaults to true).
+**--src-no-creds** _bool-value_
 
-**--src-daemon-host** _host_ Copy from docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`).
+Access the registry anonymously.
 
-**--dest-daemon-host** _host_ Copy to docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`).
+**--src-tls-verify** _bool-value_
+
+Require HTTPS and verify certificates when talking to container source registry or daemon (defaults to true).
+
+**--dest-cert-dir** _path_
+
+Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the destination registry or daemon.
+
+**--dest-no-creds** _bool-value_
+
+Access the registry anonymously.
+
+**--dest-tls-verify** _bool-value_
+
+Require HTTPS and verify certificates when talking to container destination registry or daemon (defaults to true).
+
+**--src-daemon-host** _host_
+
+Copy from docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`).
+
+**--dest-daemon-host** _host_
+
+Copy to docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`).
 
 Existing signatures, if any, are preserved as well.
 
-**--dest-compress-format** _format_ Specifies the compression format to use.  Supported values are: `gzip` and `zstd`.
+**--dest-compress-format** _format_
+
+Specifies the compression format to use.  Supported values are: `gzip` and `zstd`.
+
+**--dest-compress-level** _format_
+
+Specifies the compression level to use.  The value is specific to the compression algorithm used, e.g. for zstd the accepted values are in the range 1-20 (inclusive), while for gzip it is 1-9 (inclusive).
+
+**--src-registry-token** _token_
+
+Bearer token for accessing the source registry.
 
-**--dest-compress-level** _format_ Specifies the compression level to use.  The value is specific to the compression algorithm used, e.g. for zstd the accepted values are in the range 1-20 (inclusive), while for gzip it is 1-9 (inclusive).
+**--dest-registry-token** _token_
 
-**--src-registry-token** _Bearer token_ for accessing the source registry.
+Bearer token for accessing the destination registry.
 
-**--dest-registry-token** _Bearer token_ for accessing the destination registry.
+**--retry-times**
 
-**--retry-times**  the number of times to retry, retry wait time will be exponentially increased based on the number of failed attempts.
+The number of times to retry. Retry wait time will be exponentially increased based on the number of failed attempts.
 
 ## EXAMPLES
 

diff --git a/docs/skopeo-delete.1.md b/docs/skopeo-delete.1.md
@@ -19,24 +19,46 @@ $ docker exec -it registry /usr/bin/registry garbage-collect /etc/docker-distrib
 
 ```
 
+## OPTIONS
+
 **--authfile** _path_
 
-  Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`.
-  If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+
+**--creds** _username[:password]_
+
+Credentials for accessing the registry.
+
+**--cert-dir** _path_
+
+Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry.
+
+**--daemon-host** _host_
 
-**--creds** _username[:password]_ for accessing the registry.
+Use docker daemon host at _host_ (`docker-daemon:` transport only)
 
-**--cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry.
+**--help**, **-h**
 
-**--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true).
+Print usage statement
 
-**--no-creds** _bool-value_ Access the registry anonymously.
+**--no-creds** _bool-value_
+
+Access the registry anonymously.
 
 Additionally, the registry must allow deletions by setting `REGISTRY_STORAGE_DELETE_ENABLED=true` for the registry daemon.
 
-**--registry-token** _Bearer token_ for accessing the registry.
+**--registry-token** _token_
+
+Bearer token for accessing the registry.
+
+**--retry-times**
+
+The number of times to retry. Retry wait time will be exponentially increased based on the number of failed attempts.
+
+**--shared-blob-dir** _directory_
 
-**--retry-times**  the number of times to retry, retry wait time will be exponentially increased based on the number of failed attempts.
+Directory to use to share blobs across OCI repositories.
 
 ## EXAMPLES
 

diff --git a/docs/skopeo-inspect.1.md b/docs/skopeo-inspect.1.md
@@ -31,11 +31,19 @@ Output configuration in OCI format, default is to format in JSON format.
 
 Username and password for accessing the registry.
 
+**--daemon-host** _host_
+
+Use docker daemon host at _host_ (`docker-daemon:` transport only)
+
 **--format**, **-f**=*format*
 
 Format the output using the given Go template.
 The keys of the returned JSON can be used as the values for the --format flag (see examples below).
 
+**--help**, **-h**
+
+Print usage statement
+
 **--no-creds**
 
 Access the registry anonymously.
@@ -53,9 +61,9 @@ Registry token for accessing the registry.
 
 The number of times to retry; retry wait time will be exponentially increased based on the number of failed attempts.
 
-**--tls-verify**
+**--shared-blob-dir** _directory_
 
-Require HTTPS and verify certificates when talking to container registries (defaults to true).
+Directory to use to share blobs across OCI repositories.
 
 ## EXAMPLES
 

diff --git a/docs/skopeo-list-tags.1.md b/docs/skopeo-list-tags.1.md
@@ -10,22 +10,34 @@ Return a list of tags from _repository-name_ in a registry.
 
   _repository-name_ name of repository to retrieve tag listing from
 
-  **--authfile** _path_
+## OPTIONS
 
-  Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`.
+**--authfile** _path_
+
+Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `skopeo login`.
   If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
 
-  **--creds** _username[:password]_ for accessing the registry.
+**--creds** _username[:password]_ for accessing the registry.
+
+**--cert-dir** _path_
+
+Use certificates at _path_ (\*.crt, \*.cert, \*.key) to connect to the registry.
+
+**--help**, **-h**
+
+Print usage statement
+
+**--no-creds** _bool-value_
 
-  **--cert-dir** _path_ Use certificates at _path_ (\*.crt, \*.cert, \*.key) to connect to the registry.
+Access the registry anonymously.
 
-  **--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true).
+**--registry-token** _Bearer token_
 
-  **--no-creds** _bool-value_ Access the registry anonymously.
+Bearer token for accessing the registry.
 
-  **--registry-token** _Bearer token_ for accessing the registry.
+**--retry-times**
 
-  **--retry-times**  the number of times to retry, retry wait time will be exponentially increased based on the number of failed attempts.
+The number of times to retry. Retry wait time will be exponentially increased based on the number of failed attempts.
 
 ## REPOSITORY NAMES
 

diff --git a/docs/skopeo-login.1.md b/docs/skopeo-login.1.md
@@ -43,16 +43,14 @@ Return the logged-in user for the registry. Return error if no login is found.
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
 Default certificates directory is _/etc/containers/certs.d_.
 
-**--tls-verify**=*true|false*
-
-Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
-then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf.
-
 **--help**, **-h**
 
 Print usage statement
 
+**--verbose**, **-v**
+
+Write more detailed information to stdout
+
 ## EXAMPLES
 
 ```

diff --git a/docs/skopeo-manifest-digest.1.md b/docs/skopeo-manifest-digest.1.md
@@ -10,6 +10,12 @@ skopeo\-manifest\-digest - Compute a manifest digest for a manifest-file and wri
 
 Compute a manifest digest of _manifest-file_ and write it to standard output.
 
+## OPTIONS
+
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```sh
@@ -23,4 +29,3 @@ skopeo(1)
 ## AUTHORS
 
 Antonio Murdaca <[email protected]>, Miloslav Trmac <[email protected]>, Jhon Honce <[email protected]>
-
diff --git a/docs/skopeo-standalone-sign.1.md b/docs/skopeo-standalone-sign.1.md
@@ -15,7 +15,15 @@ This is primarily a debugging tool, useful for special cases, and usually should
 
   _key-fingerprint_ Key identity to use for signing
 
-  **--output**|**-o** output file
+## OPTIONS
+
+**--help**, **-h**
+
+Print usage statement
+
+**--output**, **-o** _output file_
+
+Write signature to _output file_.
 
 ## EXAMPLES