Update tool documentation

Author: Kevin D Smith

cicd/download-wheels.py

@@ -1,6 +1,18 @@
 #!/usr/bin/env python
 
-''' Download Wheel files from URL '''
+'''
+Download Wheel files from URL
+
+Wheel files may be stored in a staging area before being published to the
+public PyPI repository. This is done so that new packages can be tested
+before being published officially.
+
+This utility allows you to download a set of wheel files from a repository
+(optionally specifying a specific version of the package) and storing
+them in a local directory. They can then be uploaded to the final location
+using `twine`.
+
+'''
 
 import argparse
 import os
@@ -35,7 +47,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(prog='download-wheels')
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('--version', '-v', type=str, metavar='version',
                         help='version of package to download')

cicd/generate-tox-ini.py

@@ -3,6 +3,18 @@
 '''
 Generate a Tox config file for all test configurations
 
+To create a test matrix for all supported versions of Python,
+this utility takes a template `tox.ini` file and adds additional
+Tox environments to the end of it. The version of Python and
+pandas used in the environments are determined by those available
+on Anaconda.
+
+The versions of Python on Anaconda are intesected with the versions
+of Python supported in the SWAT C extensions in the package
+(e.g., _pyswat.so (2.7), _pyswa35.so (3.5), etc.). Pandas versions
+are distributed across the version of Python to increase overall
+coverage.
+
 '''
 
 import argparse
@@ -144,7 +156,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('tox_ini', type=str, metavar='ini-file',
                         help='path to tox.ini file')

cicd/get-basename.py

@@ -78,7 +78,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('root', type=str, metavar='<directory>', nargs='?', default='.',
                         help='root directory of Python package')

cicd/get-host.py

@@ -3,6 +3,27 @@
 '''
 Return a random hostname from the specified collection of names
 
+This utility is used to randomly choose a hostname from a list
+or names with a numeric range. It allows you to put bracketed
+lists or ranges of values in one or more places in the hostname
+to enumerate the possibilities. For example, if you had test
+machines named `test01`, `test02`, and `test03`. You could
+retrieve a random item from this list with the following call:
+
+    get-host.py 'test[01,02,03]'
+
+This would return one of the following:
+
+    test01
+    test02
+    test03
+
+You can also specify numeric ranges:
+
+    get-host.py 'test[01-03]'
+
+Which would return one of the above results as well.
+
 '''
 
 import argparse
@@ -37,7 +58,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('host_expr', type=str, metavar='hostname-expr', nargs='+',
                         help='hostname expression (ex. myhost[01-06].com)')

cicd/get-protocol.py

@@ -3,6 +3,11 @@
 '''
 Return the preferred CAS protocol ('cas' if TK is available; 'http' otherwise)
 
+This utility checks the package `__init__.py` file for a `__tk_version__`
+parameter that indicates the packaged version of the TK libraries.
+If it finds it, the `cas` protocol will be returned. If the value is
+set to `None`, the `http` protocol is returned.
+
 '''
 
 import argparse
@@ -16,7 +21,12 @@ def main(args):
     ''' Main routine '''
     version = None
 
-    init = glob.glob(os.path.join(args.root, 'swat', '__init__.py'))[0]
+    try:
+        init = glob.glob(os.path.join(args.root, 'swat', '__init__.py'))[0]
+    except IndexError:
+        sys.stderr.write('ERROR: Could not locate swat/__init__.py file\n')
+        sys.exit(1)
+
     with open(init, 'r') as init_in:
         for line in init_in:
             m = re.match(r'''__tk_version__\s*=\s*['"]([^'"]+)['"]''', line)
@@ -30,7 +40,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('root', type=str, metavar='<directory>',
                         default='.', nargs='?',

cicd/get-server-info.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python
 
 '''
-get-server-info
+Retrieve CAS server information from CAS log
 
-Retrieve CAS server information using CAS log.  The CAS server command
-is expected to have a -display option with a unique key for the invoked
-server.  This is used to retrieve the PID of the server process.  The
-basename of the CAS log file must match the value in the -display option.
+The CAS server command is expected to have a `-display` option with a unique
+key for the invoked server.  This is used to retrieve the PID of the server
+process.  The basename of the CAS log file must match the value in the
+`-display` option.
 
 '''
 
@@ -35,7 +35,7 @@ def main(args):
 
     '''
     if not os.path.isfile(args.log_file):
-        print_err('ERROR: File not found: {}'.format(args.log_file))
+        print_err('ERROR: File not found: {}.'.format(args.log_file))
         sys.exit(1)
 
     iters = 0
@@ -118,7 +118,8 @@ def main(args):
 
 if __name__ == '__main__':
 
-    opts = argparse.ArgumentParser(description=__doc__.strip())
+    opts = argparse.ArgumentParser(description=__doc__.strip(),
+                                   formatter_class=argparse.RawTextHelpFormatter)
 
     opts.add_argument('log_file', type=str, metavar='log-file',
                       help='path to CAS server log')

cicd/get-version.py

@@ -3,6 +3,9 @@
 '''
 Return the version of the package
 
+This command looks for the `__version__` attribute in the `swat/__init__.py`
+file to determine the package version.
+
 '''
 
 from __future__ import print_function, division, absolute_import, unicode_literals
@@ -25,7 +28,12 @@ def main(args):
 
     version = None
 
-    init = glob.glob(os.path.join(args.root, 'swat', '__init__.py'))[0]
+    try:
+        init = glob.glob(os.path.join(args.root, 'swat', '__init__.py'))[0]
+    except IndexError:
+        sys.stderr.write('ERROR: Could not locate swat/__init__.py file\n')
+        return 1
+
     with open(init, 'r') as init_in:
         for line in init_in:
             m = re.search(r'''^__version__\s*=\s*['"]([^'"]+)['"]''', line)

cicd/get-workspace-url.py

@@ -3,6 +3,11 @@
 '''
 Return the WORKSPACE as a URL
 
+Some downstream commands require the path to a Jenkins `WORKSPACE` variable
+as a URL rather than a file path. This URL must be formatted differently for
+Windows than for UNIX-like operating systems. This utility does the proper
+formatting for the host type.
+
 '''
 
 import argparse
@@ -26,7 +31,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     args = parser.parse_args()
 

cicd/install-tk.py

@@ -3,6 +3,20 @@
 '''
 Install TK libraries and C extensions
 
+In order to support the binary CAS protocol, the SWAT package needs both
+a C extension which surfaces the API for that protocol as well as the underlying
+support libraries (known as TK). This utility will download the TK libraries
+and the C extension from a repository and insert the extensions into the
+proper directory in the SWAT package directory structure. This location is:
+
+    swat/libs/{platform}/
+
+Where `{platform}` is `win` or `linux`.
+
+Since there may be multiple TK versions available at each release (for example,
+shipped and hot-fix versions), the libraries are searched for in the proper
+order.
+
 '''
 
 import argparse
@@ -277,7 +291,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description=__doc__.strip())
+    parser = argparse.ArgumentParser(description=__doc__.strip(),
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('root', type=str, nargs='?', default='.',
                         help='root directory of Python package')

cicd/promote-release-candidate.py

@@ -1,6 +1,14 @@
 #!/usr/bin/env python
 
-''' Utitily for moving a release candidate to a full release '''
+'''
+Utitily for moving a release candidate to a full release
+
+When a Github release is first created, it is done as a draft release.
+This is done so that the release can be tested and verified before going
+public as an official release. This utility is used to promote a
+draft release to a public release.
+
+'''
 
 import argparse
 import datetime
@@ -18,7 +26,15 @@
 from urllib.request import urlopen, urlretrieve
 
 
-GITHUB_TOKEN = os.environ['GITHUB_TOKEN']
+if '--help' not in sys.argv and '-h' not in sys.argv:
+    try:
+        GITHUB_TOKEN = os.environ['GITHUB_TOKEN']
+    except KeyError:
+        sys.stderr.write('ERROR: This utility requires a Github token '
+                         'for accessing the Github release API.\n')
+        sys.stderr.write('       The variable should be held in an '
+                         'environment variable named GITHUB_TOKEN.\n')
+        sys.exit(1)
 
 
 def get_repo():
@@ -250,7 +266,8 @@ def main(args):
 
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(prog='stage-release-candidate')
+    parser = argparse.ArgumentParser(prog='stage-release-candidate',
+                                     formatter_class=argparse.RawTextHelpFormatter)
 
     parser.add_argument('tag', type=tag_type, metavar='tag',
                         help='tag of the release to promote')