Somewhere in the CIv2 migration we lost the man page vs --help
cross-checker. Add it back, by adding it into the man-page-check
Makefile target; this is part of 'make validate', which is run
in CI even on CI:DOCS PRs.
As happens when CI doesn't run, things broke. Man pages got out
of sync with --help. This PR:
1) Fixes hack/xref-helpmsgs-manpages to deal with the new
"Options" (instead of "Flags") form of podman help. #8034
did part of that, but one of my review comments was
accidentally left out.
2) Fixes hack/xref-helpmsgs-manpages to deal with the new
option syntax in man pages, post- #8292, in which each
option is preceded by four hashes so as to make them
HTML <h4> elements with named anchors.
3) Fixes man pages that #8292 accidentally missed.
4) Adds man page entries for two flags that got added
to podman but not documented (pod create --network-alias,
play kube --log-driver)
Fixes: #8296
Signed-off-by: Ed Santiago <santiago@redhat.com>
Want to have man pages match commands, since we have lots of printed
man pages with using Options, we will change the command line to use
Options in --help.
Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>
There are a bunch of *.rst files in docs/source, linking sometimes
to man pages and sometimes to other .rst files. These files each
have entries of the following form:
:doc:`foo <link-to-foo>` Description of foo
...for all podman sub and sub-subcommands 'foo'.
Read all .rst files and make sure that:
- all entries in a given file are in alphabetical order
- all link-to-foo targets point to existing doc files
- every subcommand known by 'podman help' has a corresponding
doc entry in a .rst file
Signed-off-by: Ed Santiago <santiago@redhat.com>
For each podman*.md file with a subcommand table (podman,
podman-container, etc), assert that the subcommand list
is sorted.
Change is bigger than it should be, because it switches from
nice clean local per-function error counting to using a nasty
global.
Signed-off-by: Ed Santiago <santiago@redhat.com>
New hack/xref-helpmsgs-manpages script, added to CI 'gate'
task, runs 'podman [subcommand] --help' and cross-references
against man pages in docs/source/markdown/podman*.1.md
See #5453 and #5460 for instances of the problems the
script has found.
The careful reader will find an alarming number of special-case
bypasses. These are a tradeoff I am making: to get perfect
coverage with no handwaving, it would be necessary to make
drastic changes to some man pages, and I believe those would
be counterproductive.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Ed Santiago
Daniel J Walsh
Jhon Honce