Added output format options for --help

lib/vsc/utils/docs.py

@@ -0,0 +1,66 @@
+# #
+# Copyright 2015-2015 Ghent University
+#
+# This file is part of vsc-base,
+# originally created by the HPC team of Ghent University (http://ugent.be/hpc/en),
+# with support of Ghent University (http://ugent.be/hpc),
+# the Flemish Supercomputer Centre (VSC) (https://vscentrum.be/nl/en),
+# the Hercules foundation (http://www.herculesstichting.be/in_English)
+# and the Department of Economy, Science and Innovation (EWI) (http://www.ewi-vlaanderen.be/en).
+#
+# http://github.com/hpcugent/vsc-base
+#
+# vsc-base is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Library General Public License as
+# published by the Free Software Foundation, either version 2 of
+# the License, or (at your option) any later version.
+#
+# vsc-base is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Library General Public License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with vsc-base. If not, see <http://www.gnu.org/licenses/>.
+# #
+"""
+A class that has some support functions for generating rst documentation
+
+@author: Caroline De Brouwer (Ghent University)
+"""
+
+def det_col_width(entries, title):
+    """Determine column width based on column title and list of entries."""
+    return max(map(len, entries + [title]))
+
+def mk_rst_table(titles, values):
+    """
+    Returns an rst table with given titles and values (a nested list of string values for each column)
+    """
+    num_col = len(titles)
+    table = []
+    col_widths = []
+    tmpl = []
+    line= []
+
+    # figure out column widths
+    for i in range(0, num_col):
+        col_widths.append(det_col_width(values[i], titles[i]))
+
+        # make line template
+        tmpl.append('{' + str(i) + ':{c}<' + str(col_widths[i]) + '}')
+        line.append('') # needed for table line
+
+    line_tmpl = '   '.join(tmpl)
+    table_line = line_tmpl.format(*line, c="=")
+
+    table.append(table_line)
+    table.append(line_tmpl.format(*titles, c=' '))
+    table.append(table_line)
+
+    for i in range(0, len(values[0])):
+        table.append(line_tmpl.format(*[v[i] for v in values], c=' '))
+
+    table.extend([table_line, ''])
+
+    return table

lib/vsc/utils/generaloption.py

@@ -1,5 +1,4 @@
-#
-#
+# #
 # Copyright 2011-2014 Ghent University
 #
 # This file is part of vsc-base,
@@ -46,6 +45,7 @@
 from optparse import SUPPRESS_HELP as nohelp  # supported in optparse of python v2.4
 from optparse import _ as _gettext  # this is gettext normally
 from vsc.utils.dateandtime import date_parser, datetime_parser
+from vsc.utils.docs import mk_rst_table
 from vsc.utils.fancylogger import getLogger, setLogLevel, getDetailsLogLevels
 from vsc.utils.missing import shell_quote, nub
 from vsc.utils.optcomplete import autocomplete, CompleterOption
@@ -162,9 +162,9 @@ class ExtOption(CompleterOption):
     DISABLE = 'disable'  # inverse action
 
     EXTOPTION_EXTRA_OPTIONS = ('date', 'datetime', 'regex', 'add', 'add_first', 'add_flex',)
-    EXTOPTION_STORE_OR = ('store_or_None',)  # callback type
+    EXTOPTION_STORE_OR = ('store_or_None', 'formathelp')  # callback type
     EXTOPTION_LOG = ('store_debuglog', 'store_infolog', 'store_warninglog',)
-    EXTOPTION_HELP = ('shorthelp', 'confighelp',)
+    EXTOPTION_HELP = ('shorthelp', 'confighelp', 'help')
 
     ACTIONS = Option.ACTIONS + EXTOPTION_EXTRA_OPTIONS + EXTOPTION_STORE_OR + EXTOPTION_LOG + EXTOPTION_HELP
     STORE_ACTIONS = Option.STORE_ACTIONS + EXTOPTION_EXTRA_OPTIONS + EXTOPTION_LOG + ('store_or_None',)
@@ -211,9 +211,10 @@ def store_or(option, opt_str, value, parser, *args, **kwargs):
             self.callback = store_or
             self.callback_kwargs = {
                 'orig_default': copy.deepcopy(self.default),
-                }
+            }
             self.action = 'callback'  # act as callback
-            if self.store_or == 'store_or_None':
+
+            if self.store_or in ('store_or_None', 'formathelp'):
                 self.default = None
             else:
                 self.log.raiseException("_set_attrs: unknown store_or %s" % self.store_or, exception=ValueError)
@@ -222,7 +223,13 @@ def take_action(self, action, dest, opt, value, values, parser):
         """Extended take_action"""
         orig_action = action  # keep copy
 
-        if action == 'shorthelp':
+        # dest is None for actions like shorthelp and confighelp
+        if dest and getattr(parser._long_opt.get('--'+dest, ''), 'store_or', '') == 'formathelp':
+            Option.take_action(self, action, dest, opt, value, values, parser)
+            fn = getattr(parser, 'print_%shelp' % values.help)
+            fn()
+            parser.exit()
+        elif action == 'shorthelp':
             parser.print_shorthelp()
             parser.exit()
         elif action == 'confighelp':
@@ -567,8 +574,7 @@ def print_shorthelp(self, fh=None):
 
         self.print_help(fh)
 
-    def print_help(self, fh=None):
-        """Intercept print to file to print to string and remove the ENABLE/DISABLE options from help"""
+    def check_help(self, fh):
         if self.help_to_string:
             self.help_to_file = StringIO.StringIO()
         if fh is None:
@@ -583,9 +589,63 @@ def _is_enable_disable(x):
             for opt in self._get_all_options():
                 # remove all long_opts with ENABLE/DISABLE naming
                 opt._long_opts = [x for x in opt._long_opts if not _is_enable_disable(x)]
+        return fh
 
+    def print_help(self, fh=None):
+        """Intercept print to file to print to string and remove the ENABLE/DISABLE options from help"""
+        fh = self.check_help(fh)
         OptionParser.print_help(self, fh)
 
+    def print_rsthelp(self, fh=None):
+        """ Print help in rst format """
+        fh = self.check_help(fh)
+        result = []
+        title = "Easybuild help"
+        result.extend([title, "=" * len(title)])
+        if self.usage:
+            result.append("Usage: ``%s``" % self.get_usage().replace("Usage: ", '').strip())
+            result.append('')
+        if self.description:
+            result.append(self.description)
+            result.append('')
+
+        result.append(self.format_option_rsthelp())
+
+        print "\n".join(result)
+
+    def format_option_rsthelp(self, formatter=None):
+        """ Formatting for help in rst format """
+        if not formatter:
+            formatter = self.formatter
+        formatter.store_option_strings(self)
+
+        res = []
+        opt_title = "Options"
+        res.extend([opt_title, '-' * len(opt_title)])
+        titles = ["Option", "Help"]
+        values = [[],[]]
+        for opt in self.option_list:
+            if not opt.help is nohelp:
+                values[0].append('``%s``' % formatter.option_strings[opt])
+                values[1].append(formatter.expand_default(opt))
+
+        res.extend(mk_rst_table(titles, values))
+        res.append('')
+
+        for group in self.option_groups:
+            res.extend([group.title, '-' * len(group.title)])
+            values[0] = []
+            values[1] = []
+            for opt in group.option_list:
+                if not opt.help is nohelp:
+                    values[0].append('``%s``' % formatter.option_strings[opt])
+                    values[1].append(formatter.expand_default(opt))
+
+            res.extend(mk_rst_table(titles, values))
+            res.append('')
+
+        return '\n'.join(res)
+
     def print_confighelp(self, fh=None):
         """Print help as a configfile."""
 
@@ -633,7 +693,8 @@ def _add_help_option(self):
                         help=_gettext("show short help message and exit"))
         self.add_option("-%s" % self.longhelp[0],
                         self.longhelp[1],  # *self.longhelp[1:], syntax error in Python 2.4
-                        action="help",
+                        action="formathelp",
+                        default='',
                         help=_gettext("show full help message and exit"))
         self.add_option("--confighelp",
                         action="confighelp",
@@ -792,6 +853,7 @@ def __init__(self, **kwargs):
             'usage': kwargs.get('usage', self.USAGE),
             'version': self.VERSION,
         })
+
         self.parser = self.PARSER(**kwargs)
         self.parser.allow_interspersed_args = self.INTERSPERSED
 
@@ -1423,6 +1485,8 @@ def generate_cmd_line(self, ignore=None, add_default=None):
         opt_dests.sort()
 
         for opt_dest in opt_dests:
+            # help is store_or_None, but is not a processed option, so skip it
+            if opt_dest in ExtOption.EXTOPTION_HELP: continue
             opt_value = self.options.__dict__[opt_dest]
             # this is the action as parsed by the class, not the actual action set in option
             # (eg action store_or_None is shown here as store_or_None, not as callback)
@@ -1453,7 +1517,7 @@ def generate_cmd_line(self, ignore=None, add_default=None):
                                (opt_name, opt_value))
                 continue
 
-            if action in ('store_or_None',):
+            if action in ('store_or_None', 'formathelp'):
                 if opt_value == default:
                     self.log.debug("generate_cmd_line %s adding %s (value is default value %s)" %
                                    (action, opt_name, opt_value))