mirror of https://github.com/containers/podman.git
[CI:DOCS] Add CI check for SEE ALSO in man pages
Add new CI check to confirm that links and references in SEE ALSO sections are properly formatted and that links are valid (at least in theory: we do no actual URL fetching to test for 404). The check is piggybacked into existing xref-helpmsgs-manpages script. It could conceivably be more elegant to write a separate tool for this purpose, but I don't wish to duplicate the logic for finding and reading markdown files. Script identified various problems, which I fix in this PR: . missing '**' (asterisks) around some references, or '**' in the wrong place. . links pointing to github.com/.../tree/ instead of /blob/ (github redirects those automatically, but I like consistency) . a few copy-paste errors, e.g. subgid linking to subuid. Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
parent
2e6231bcbc
commit
6236be4ff9
|
@ -141,4 +141,4 @@ $ podman auto-update
|
|||
```
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, sd_notify(3), systemd.unit(5)
|
||||
**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**
|
||||
|
|
|
@ -1021,7 +1021,7 @@ If you are using `useradd` within your build script, you should pass the
|
|||
useradd to stop creating the lastlog file.
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[useradd(8)](https://www.unix.com/man-page/redhat/8/useradd)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[Containerfile(5)](https://github.com/containers/buildah/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/buildah/blob/main/docs/containerignore.5.md)**
|
||||
**[podman(1)](podman.1.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[useradd(8)](https://www.unix.com/man-page/redhat/8/useradd)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[Containerfile(5)](https://github.com/containers/buildah/blob/main/docs/Containerfile.5.md)**, **[containerignore(5)](https://github.com/containers/buildah/blob/main/docs/containerignore.5.md)**
|
||||
|
||||
## HISTORY
|
||||
Aug 2020, Additional options and .containerignore added by Dan Walsh `<dwalsh@redhat.com>`
|
||||
|
|
|
@ -61,4 +61,4 @@ completion output to a file and source that to the user's powershell profile.
|
|||
More information about profiles is available with **Get-Help about_Profiles**.
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, zsh(1), fish(1), powershell(1)
|
||||
**[podman(1)](podman.1.md)**, **zsh(1)**, **fish(1)**, **powershell(1)**
|
||||
|
|
|
@ -51,7 +51,7 @@ $ podman container cleanup mywebserver myflaskserver 860a4b23
|
|||
```
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, conmon(8)
|
||||
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
|
||||
|
||||
## HISTORY
|
||||
Jun 2018, Originally compiled by Dan Walsh <dwalsh@redhat.com>
|
||||
|
|
|
@ -84,7 +84,7 @@ $ podman container runlabel --display run foobar
|
|||
```
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**
|
||||
**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**
|
||||
|
||||
## HISTORY
|
||||
August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot com)
|
||||
|
|
|
@ -1537,7 +1537,7 @@ page.
|
|||
NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**.
|
||||
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**
|
||||
|
||||
## HISTORY
|
||||
October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman `<dwalsh@redhat.com>`
|
||||
|
|
|
@ -235,7 +235,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS
|
|||
bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser
|
||||
```
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.5.md)**
|
||||
**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, **systemctl(1)**, **systemd.unit(5)**, **systemd.service(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
|
||||
|
||||
## HISTORY
|
||||
April 2020, Updated details and added use case to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)
|
||||
|
|
|
@ -53,7 +53,6 @@ $ podman rmi -a -f
|
|||
**125** The command fails for any other reason
|
||||
|
||||
## SEE ALSO
|
||||
podman(1), skopeo-delete(1)
|
||||
**[podman(1)](podman.1.md)**, **[skopeo-delete(1)](https://github.com/containers/skopeo/blob/main/docs/skopeo-delete.1.md)**
|
||||
|
||||
## HISTORY
|
||||
|
|
|
@ -1891,7 +1891,7 @@ page.
|
|||
NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
|
||||
|
||||
## SEE ALSO
|
||||
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**.
|
||||
**[podman(1)](podman.1.md)**, **[podman-save(1)](podman-save.1.md)**, **[podman-ps(1)](podman-ps.1.md)**, **[podman-attach(1)](podman-attach.1.md)**, **[podman-pod-create(1)](podman-pod-create.1.md)**, **[podman-port(1)](podman-port.1.md)**, **[podman-start(1)](podman-start.1.md)**, **[podman-kill(1)](podman-kill.1.md)**, **[podman-stop(1)](podman-stop.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-rm(1)](podman-rm.1.md)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)**, **[setsebool(8)](https://man7.org/linux/man-pages/man8/setsebool.8.html)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[fuse-overlayfs(1)](https://github.com/containers/fuse-overlayfs/blob/main/fuse-overlayfs.1.md)**, **proc(5)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**, **personality(2)**
|
||||
|
||||
## HISTORY
|
||||
September 2018, updated by Kunal Kushwaha `<kushwaha_kunal_v7@lab.ntt.co.jp>`
|
||||
|
|
|
@ -144,7 +144,6 @@ Note: This works only with registries that implement the v2 API. If tried with a
|
|||
registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
|
||||
|
||||
## SEE ALSO
|
||||
podman(1), containers-registries.conf(5)
|
||||
**[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)**
|
||||
|
||||
## HISTORY
|
||||
|
|
|
@ -400,7 +400,7 @@ The Network File System (NFS) and other distributed file systems (for example: L
|
|||
For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/master/troubleshooting.md).
|
||||
|
||||
## SEE ALSO
|
||||
**[containers-mounts.conf(5)](https://github.com/containers/common/blob/main/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **oci-hooks**(5), **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
|
||||
**[containers-mounts.conf(5)](https://github.com/containers/common/blob/main/docs/containers-mounts.conf.5.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**, **[buildah(1)](https://github.com/containers/buildah/blob/main/docs/buildah.1.md)**, **oci-hooks(5)**, **[containers-policy.json(5)](https://github.com/containers/image/blob/main/docs/containers-policy.json.5.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[subuid(5)](https://www.unix.com/man-page/linux/5/subuid)**, **[subgid(5)](https://www.unix.com/man-page/linux/5/subgid)**, **[slirp4netns(1)](https://github.com/rootless-containers/slirp4netns/blob/master/slirp4netns.1.md)**, **[conmon(8)](https://github.com/containers/conmon/blob/main/docs/conmon.8.md)**
|
||||
|
||||
## HISTORY
|
||||
Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com>
|
||||
|
|
|
@ -54,6 +54,11 @@ option is listed in the appropriate man page and vice-versa.
|
|||
|
||||
$ME invokes '\$PODMAN' (default: $Default_Podman).
|
||||
|
||||
In the spirit of shoehorning functionality where it wasn't intended,
|
||||
$ME also checks the SEE ALSO section of each man page
|
||||
to ensure that references and links are properly formatted
|
||||
and valid.
|
||||
|
||||
Exit status is zero if no inconsistencies found, one otherwise
|
||||
|
||||
OPTIONS:
|
||||
|
@ -286,6 +291,9 @@ sub podman_man {
|
|||
elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) {
|
||||
$section = 'commands';
|
||||
}
|
||||
elsif ($line =~ /^\#\#\s+SEE\s+ALSO/) {
|
||||
$section = 'see-also';
|
||||
}
|
||||
elsif ($line =~ /^\#\#[^#]/) {
|
||||
$section = '';
|
||||
}
|
||||
|
@ -340,6 +348,11 @@ sub podman_man {
|
|||
}
|
||||
}
|
||||
}
|
||||
|
||||
# It's easy to make mistakes in the SEE ALSO elements.
|
||||
elsif ($section eq 'see-also') {
|
||||
_check_seealso_links( "$subpath:$.", $line );
|
||||
}
|
||||
}
|
||||
close $fh;
|
||||
|
||||
|
@ -427,5 +440,119 @@ sub podman_rst {
|
|||
|
||||
# END data gathering
|
||||
###############################################################################
|
||||
# BEGIN sanity checking of SEE ALSO links
|
||||
|
||||
##########################
|
||||
# _check_seealso_links # Check formatting and link validity.
|
||||
##########################
|
||||
sub _check_seealso_links {
|
||||
my $path = shift;
|
||||
my $line = shift;
|
||||
|
||||
return if ! $line;
|
||||
|
||||
# Line must be a comma-separated list of man page references, e.g.
|
||||
# **foo(1)**, **[podman-bar(1)](podman-bar.1.md)**, **[xxx(8)](http...)**
|
||||
TOKEN:
|
||||
for my $token (split /,\s+/, $line) {
|
||||
# Elements must be separated by comma and space. (We don't do further
|
||||
# checks here, so it's possible for the dev to add the space and then
|
||||
# have us fail on the next iteration. I choose not to address that.)
|
||||
if ($token =~ /,/) {
|
||||
warn "$ME: $path: please add space after comma: '$token'\n";
|
||||
++$Errs;
|
||||
next TOKEN;
|
||||
}
|
||||
|
||||
# Each token must be of the form '**something**'
|
||||
if ($token !~ s/^\*\*(.*)\*\*$/$1/) {
|
||||
if ($token =~ /\*\*/) {
|
||||
warn "$ME: $path: '$token' has asterisks in the wrong place\n";
|
||||
}
|
||||
else {
|
||||
warn "$ME: $path: '$token' should be bracketed by '**'\n";
|
||||
}
|
||||
++$Errs;
|
||||
next TOKEN;
|
||||
}
|
||||
|
||||
# Is it a markdown link?
|
||||
if ($token =~ /^\[(\S+)\]\((\S+)\)$/) {
|
||||
my ($name, $link) = ($1, $2);
|
||||
if ($name =~ /^(.*)\((\d)\)$/) {
|
||||
my ($base, $section) = ($1, $2);
|
||||
if (-e "$Markdown_Path/$base.$section.md" || -e "$Markdown_Path/links/$base.$section") {
|
||||
if ($link ne "$base.$section.md") {
|
||||
warn "$ME: $path: inconsistent link $name -> $link, expected $base.$section.md\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
else {
|
||||
if (! _is_valid_external_link($base, $section, $link)) {
|
||||
warn "$ME: $path: invalid link $name -> $link\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
}
|
||||
else {
|
||||
warn "$ME: $path: could not parse '$name' as 'manpage(N)'\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
|
||||
# Not a markdown link; it must be a plain man reference, e.g. 'foo(5)'
|
||||
elsif ($token =~ m!^(\S+)\((\d+)\)$!) {
|
||||
my ($base, $section) = ($1, $2);
|
||||
|
||||
# Unadorned 'podman-foo(1)' must be a link.
|
||||
if (-e "$Markdown_Path/$base.$section.md" || -e "$Markdown_Path/links/$base.$section") {
|
||||
warn "$ME: $path: '$token' should be '[$token]($base.$section.md)'\n";
|
||||
++$Errs;
|
||||
}
|
||||
|
||||
# Link to man page foo(5) but without a link. This is not an error
|
||||
# but Ed may sometimes want to see those on a manual test run.
|
||||
warn "$ME: $path: plain '$token' would be so much nicer as a link\n"
|
||||
if $verbose;
|
||||
}
|
||||
else {
|
||||
warn "$ME: $path: invalid token '$token'\n";
|
||||
++$Errs;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#############################
|
||||
# _is_valid_external_link # Tries to validate links to external man pages
|
||||
#############################
|
||||
#
|
||||
# This performs no actual fetches, so we can't actually check for 404.
|
||||
# All we do is ensure that links conform to standard patterns. This is
|
||||
# good for catching things like 'conmon(8)' pointing to a .5 URL, or
|
||||
# linking to .md instead of .html.
|
||||
#
|
||||
# FIXME: we could actually rewrite this so as to offer hints on what to fix.
|
||||
# That's a lot of work, and a lot of convoluted code, for questionable ROI.
|
||||
#
|
||||
sub _is_valid_external_link {
|
||||
my ($base, $section, $link) = @_;
|
||||
|
||||
return 1 if $link =~ m!^https://github\.com/\S+/blob/(main|master)(/.*)?/\Q$base\E\.$section\.md!;
|
||||
|
||||
return 1 if $link =~ m!^https://.*unix\.com/man-page/(linux|redhat)/$section/$base$!;
|
||||
return 1 if $link eq "https://man7\.org/linux/man-pages/man$section/$base\.$section\.html";
|
||||
|
||||
if ($base =~ /systemd/) {
|
||||
return 1 if $link eq "https://www.freedesktop.org/software/systemd/man/$base.html";
|
||||
}
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
# END sanity checking of SEE ALSO links
|
||||
###############################################################################
|
||||
|
||||
1;
|
||||
|
|
Loading…
Reference in New Issue