mirror of https://github.com/containers/podman.git
Merge pull request #12258 from edsantiago/xref_manpages_see_also
[CI:DOCS] Add CI check for SEE ALSO in man pages
This commit is contained in:
OpenShift Merge Robot
GitHub
commit
9dddc47d28
|
|
@ -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