Merge pull request #7458 from Luap99/fix-remote-docs

[CI:DOCS] Update podman-remote docs
containers · Aug 27, 2020 · 72c5b35 · 72c5b35
2 parents b13af45 + 7dce7a6
commit 72c5b35
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 29 deletions.
diff --git a/docs/remote-docs.sh b/docs/remote-docs.sh
@@ -12,21 +12,22 @@ function usage() {
     echo >&2 "$0 PLATFORM TARGET SOURCES..."
     echo >&2 "PLATFORM: Is either linux, darwin or windows."
     echo >&2 "TARGET: Is the directory where files will be staged. eg, docs/build/remote/linux"
-    echo >&2 "SOURCES: Are the directories of source files. eg, docs/markdown"
+    echo >&2 "SOURCES: Are the directories of source files. eg, docs/source/markdown"
 }
 
 function fail() {
-    echo >&2 -e "$@\n"
-    usage
+    echo >&2 -e "$(dirname $0): $@\n"
     exit 1
 }
 
 case $PLATFORM in
 darwin|linux)
     PUBLISHER=man_fn
+    ext=1
     ;;
 windows)
     PUBLISHER=html_fn
+    ext=1.md
     ;;
 -help)
     usage
@@ -54,7 +55,7 @@ function man_fn() {
     local dir=$(dirname $page)
 
     if [[ ! -f $page ]]; then
-        page=$dir/links/${file%.*}.1
+        page=$dir/links/${file%.*}.$ext
     fi
     install $page $TARGET/${file%%.*}.1
 }
@@ -72,6 +73,22 @@ function html_fn() {
     pandoc --ascii --lua-filter=docs/links-to-html.lua -o $TARGET/${file%%.*}.html $markdown
 }
 
+# Run 'podman help' (possibly against a subcommand, e.g. 'podman help image')
+# and return a list of each first word under 'Available Commands', that is,
+# the command name but not its description.
+function podman_commands() {
+    $PODMAN help "$@" |\
+        awk '/^Available Commands:/{ok=1;next}/^Flags:/{ok=0}ok { print $1 }' |\
+        grep .
+}
+
+function podman_all_commands(){
+    for cmd in $(podman_commands "$@") ; do
+		echo $@ $cmd
+        podman_all_commands $@ $cmd
+	done
+}
+
 ## pub_pages finds and publishes the remote manual pages
 function pub_pages() {
     local source=$1
@@ -80,12 +97,19 @@ function pub_pages() {
         $publisher $f
     done
 
-    for c in "container" "image" "pod" "volume" ""; do
-        local cmd=${c:+-$c}
-        for s in $($PODMAN $c --help | sed -n '/^Available Commands:/,/^Flags:/p' | sed -e '1d;$d' -e '/^$/d' | awk '{print $1}'); do
-            $publisher $(echo $source/podman$cmd-$s.*)
-        done
-    done
+
+    while IFS= read -r cmd; do
+        file="podman-${cmd// /-}"
+
+        # Source dir may have man (.1) files (linux/darwin) or .1.md (windows)
+        # but the links subdir will always be .1 (man) files
+        if [ -f $source/$file.$ext -o -f $source/links/$file.1 ]; then
+            $publisher $(echo $source/$file.$ext)
+        else
+            # This is worth failing CI for
+            fail "no doc file nor link $source/$file.$ext for 'podman $cmd'"
+        fi
+    done <<< "$(podman_all_commands)"
 }
 
 ## sed syntax is different on darwin and linux

diff --git a/docs/source/markdown/podman-remote.1.md b/docs/source/markdown/podman-remote.1.md
@@ -17,7 +17,9 @@ Podman uses Buildah(1) internally to create container images. Both tools share i
 (not container) storage, hence each can use or manipulate images (but not containers)
 created by the other.
 
-Podman-remote provides a local client interacting with a Podman backend node through a RESTful API tunneled through a ssh connection. In this context, a Podman node is a Linux system with Podman installed on it and the API service activated. Credentials for this session can be passed in using flags, environment variables, or in `podman-remote.conf`
+Podman-remote provides a local client interacting with a Podman backend node through a RESTful API tunneled through a ssh connection. In this context, a Podman node is a Linux system with Podman installed on it and the API service activated. Credentials for this session can be passed in using flags, environment variables, or in `containers.conf`.
+
+The `containers.conf` file should be placed under `$HOME/.config/containers/containers.conf` on Linux and Mac and `%APPDATA%\containers\containers.conf` on Windows.
 
 **podman [GLOBAL OPTIONS]**
 
@@ -31,29 +33,19 @@ Remote connection name
 
 Print usage statement
 
-**--log-level**=*level*
-
-Log messages above specified level: debug, info, warn, error (default), fatal or panic
-
-**--port**=*integer*
-
-Use an alternative port for the ssh connections.  The default port is 22
+**--identity**=*path*
 
-**--remote-config-path**=*path*
+Path to ssh identity file. If the identity file has been encrypted, Podman prompts the user for the passphrase.
+If no identity file is provided and no user is given, Podman defaults to the user running the podman command.
+Podman prompts for the login password on the remote server.
 
-Alternate path for configuration file
-
-**--remote-host**=*ip*
-
-Remote host IP
-
-**--syslog**
+**--log-level**=*level*
 
-Output logging information to syslog as well as the console
+Log messages above specified level: debug, info, warn, error (default), fatal or panic
 
-**--username**=*string*
+**--url**=*value*
 
-Username on the remote host (defaults to current username)
+URL to access Podman service (default from `containers.conf`, rootless "unix://run/user/$UID/podman/podman.sock" or as root "unix://run/podman/podman.sock).
 
 **--version**