From 3b1f4fda721addc9f3c2c273091f76148ebae9d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Lis=C3=A1k?= <peter.lisak@firma.seznam.cz>
Date: Fri, 13 Nov 2015 17:20:20 +0100
Subject: [PATCH] Unification of manpages and docstrings
* adding missing options
* unification of help
Change-Id: I2365e66433b63de8fd4da205611d9c1bf3bb6730
---
doc/manpages/swift.1 | 42 +++++++++++++++++++++++++++---------------
swiftclient/shell.py | 21 ++++++++++++---------
2 files changed, 39 insertions(+), 24 deletions(-)
diff --git a/doc/manpages/swift.1 b/doc/manpages/swift.1
index 4cfc23fd..8672a11d 100644
--- a/doc/manpages/swift.1
+++ b/doc/manpages/swift.1
@@ -36,25 +36,25 @@ several types of operations.
.SH COMMANDS
.PP
-\fBstat\fR [\fIcontainer\fR] [\fIobject\fR]
+\fBstat\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR]
.RS 4
Displays information for the account, container, or object depending on the args given (if any).
In verbose mode, the Storage URL and the authentication token are displayed
-as well.
+as well. Option \-\-lh reports sizes in human readable format similar to ls \-lh.
.RE
\fBlist\fR [\fIcommand-options\fR] [\fIcontainer\fR]
.RS 4
Lists the containers for the account or the objects for a container.
-The \-p or \-\-prefix is an option that will only list items beginning
-with that prefix. The \-d or \-\-delimiter is option (for container listings only)
-that will roll up items with the given delimiter (see OpenStack Swift general
-documentation for what this means).
+The \-p <prefix> or \-\-prefix <prefix> is an option that will only list items beginning
+with that prefix. The \-d <delim> or \-\-delimiter <delim> is option
+(for container listings only) that will roll up items with the given
+delimiter (see OpenStack Swift general documentation for what this means).
-The \-l and \-\-lh options provide more detail, similar to ls \-l and ls \-lh, the latter
+The \-l or \-\-long and \-\-lh options provide more detail, similar to ls \-l and ls \-lh, the latter
providing sizes in human readable format (eg 3K, 12M, etc). These latter 2 switches
use more overhead to get those details, which is directly proportional to the number
-of container or objects being listed.
+of container or objects being listed. With the \-t or \-\-total option they only report totals.
.RE
\fBupload\fR [\fIcommand-options\fR] container file_or_directory [\fIfile_or_directory\fR] [...]
@@ -64,7 +64,7 @@ remaining args. The \-c or \-\-changed is an option that will only upload files
that have changed since the last upload. The \-\-object-name <object\-name> is
an option that will upload file and name object to <object-name> or upload dir
and use <object\-name> as object prefix. The \-S <size> or \-\-segment\-size <size>
-and \-\-leave\-segments are options as well (see \-\-help for more).
+and \-\-leave\-segments and others are options as well (see swift upload \-\-help for more).
.RE
\fBpost\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR]
@@ -75,6 +75,7 @@ automatically; but this is not true for accounts and objects. Containers
also allow the \-r (or \-\-read\-acl) and \-w (or \-\-write\-acl) options. The \-m
or \-\-meta option is allowed on all and used to define the user meta data
items to set in the form Name:Value. This option can be repeated.
+For more details and options see swift post \-\-help.
\fBExample\fR: post \-m Color:Blue \-m Size:Large
.RE
@@ -83,9 +84,10 @@ items to set in the form Name:Value. This option can be repeated.
Downloads everything in the account (with \-\-all), or everything in a
container, or a list of objects depending on the args given. For a single
object download, you may use the \-o [\-\-output] <filename> option to
-redirect the output to a specific file or if "-" then just redirect to stdout.
+redirect the output to a specific file or if "-" then just redirect to stdout or
+with \-\-no-download actually not to write anything to disk.
You can specify optional headers with the repeatable cURL-like option
-\-H [\-\-header].
+\-H [\-\-header]. For more details and options see swift download \-\-help.
.RE
\fBdelete\fR [\fIcommand-options\fR] [\fIcontainer\fR] [\fIobject\fR] [\fIobject\fR] [...]
@@ -93,6 +95,7 @@ You can specify optional headers with the repeatable cURL-like option
Deletes everything in the account (with \-\-all), or everything in a container,
or a list of objects depending on the args given. Segments of manifest objects
will be deleted as well, unless you specify the \-\-leave\-segments option.
+For more details and options see swift delete \-\-help.
.RE
\fBcapabilities\fR [\fIproxy-url\fR]
@@ -104,7 +107,7 @@ is not provided the storage-url retrieved after authentication is used as
proxy-url.
.RE
-\fBtempurl\fR \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR [\fI--absolute\fR]
+\fBtempurl\fR [\fIcommand-option\fR] \fImethod\fR \fIseconds\fR \fIpath\fR \fIkey\fR
.RS 4
Generates a temporary URL allowing unauthenticated access to the Swift object
at the given path, using the given HTTP method, for the given number of
@@ -114,20 +117,29 @@ should expire. \fBExample\fR: tempurl GET $(date -d "Jan 1 2016" +%s)
/v1/AUTH_foo/bar_container/quux.md my_secret_tempurl_key --absolute
.RE
+\fBauth\fR
+.RS 4
+Display auth related authentication variables in shell friendly format.
+For examples see swift auth \-\-help.
+.RE
+
.SH OPTIONS
.PD 0
.IP "--version Show program's version number and exit"
-.IP "-h, --help Show this (or any subcommand) help message and exit"
+.IP "-h, --help Show this (or any subcommand if after command) help message and exit"
.IP "-s, --snet Use SERVICENET internal network"
.IP "-v, --verbose Print more info"
.IP "-q, --quiet Suppress status output"
.IP "-A AUTH, --auth=AUTH URL for obtaining an auth token "
.IP "-U USER, --user=USER User name for obtaining an auth token"
-.IP "-V 1|2 Authentication protocol version"
+.IP "-V 1|2, --auth-version=VERSION Authentication protocol version"
.IP "-K KEY, --key=KEY Key for obtaining an auth token"
.IP "--os-storage-url=URL Use this instead of URL returned from auth"
-
+.IP "--os-help Show all OpenStack authentication options"
.PD
+.RS 4
+For more options see swift \-\-help and swift \-\-os-help.
+.RE
.SH EXAMPLE
diff --git a/swiftclient/shell.py b/swiftclient/shell.py
index 15ca5706..0b8af5cb 100755
--- a/swiftclient/shell.py
+++ b/swiftclient/shell.py
@@ -54,15 +54,15 @@ def immediate_exit(signum, frame):
st_delete_options = '''[--all] [--leave-segments]
[--object-threads <threads>]
[--container-threads <threads>]
- <container> [object]
+ [<container>] [<object>] [...]
'''
st_delete_help = '''
Delete a container or objects within a container.
Positional arguments:
- <container> Name of container to delete from.
- [object] Name of object to delete. Specify multiple times
+ [<container>] Name of container to delete from.
+ [<object>] Name of object to delete. Specify multiple times
for multiple objects.
Optional arguments:
@@ -156,7 +156,7 @@ st_download_options = '''[--all] [--marker] [--prefix <prefix>]
[--object-threads <threads>]
[--container-threads <threads>] [--no-download]
[--skip-identical] [--remove-prefix]
- [--header <header:value>]
+ [--header <header:value>] [--no-shuffle]
<container> <object>
'''
@@ -376,7 +376,7 @@ def st_download(parser, args, output_manager):
st_list_options = '''[--long] [--lh] [--totals] [--prefix <prefix>]
- [--delimiter <delimiter>]
+ [--delimiter <delimiter>] [container]
'''
st_list_help = '''
@@ -390,8 +390,10 @@ Optional arguments:
--lh Report sizes in human readable format similar to
ls -lh.
-t, --totals Used with -l or --lh, only report totals.
- -p, --prefix Only list items beginning with the prefix.
- -d, --delimiter Roll up items with the given delimiter. For containers
+ -p <prefix>, --prefix <prefix>
+ Only list items beginning with the prefix.
+ -d <delim>, --delimiter <delim>
+ Roll up items with the given delimiter. For containers
only. See OpenStack Swift API documentation for what
this means.
'''.strip('\n')
@@ -690,7 +692,7 @@ st_upload_options = '''[--changed] [--skip-identical] [--segment-size <size>]
[--object-threads <thread>] [--segment-threads <threads>]
[--header <header>] [--use-slo] [--ignore-checksum]
[--object-name <object-name>]
- <container> <file_or_directory>
+ <container> <file_or_directory> [<file_or_directory>] [...]
'''
st_upload_help = ''' Uploads specified files and directories to the given container.
@@ -1006,7 +1008,8 @@ def st_auth(parser, args, thread_manager):
print('export OS_AUTH_TOKEN=%s' % sh_quote(token))
-st_tempurl_options = '<method> <seconds> <path> <key>'
+st_tempurl_options = '''[--absolute]
+ <method> <seconds> <path> <key>'''
st_tempurl_help = '''