Merge pull request #4117 from boegel/docs_md

add support for using --output-format=md (MarkDown)
easybuilders · Jan 4, 2023 · e784549 · e784549
2 parents afbf5a6 + dd50ce6
commit e784549
Show file tree

Hide file tree

Showing 8 changed files with 1,507 additions and 154 deletions.
diff --git a/easybuild/base/generaloption.py b/easybuild/base/generaloption.py
@@ -44,7 +44,7 @@
 from easybuild.base.fancylogger import getLogger, setroot, setLogLevel, getDetailsLogLevels
 from easybuild.base.optcomplete import autocomplete, CompleterOption
 from easybuild.tools.py2vs3 import StringIO, configparser, string_type, subprocess_popen_text
-from easybuild.tools.utilities import mk_rst_table, nub, shell_quote
+from easybuild.tools.utilities import mk_md_table, mk_rst_table, nub, shell_quote
 
 try:
     import gettext
@@ -65,7 +65,7 @@ def _gettext(message):
         return message
 
 
-HELP_OUTPUT_FORMATS = ['', 'rst', 'short', 'config']
+HELP_OUTPUT_FORMATS = ['', 'md', 'rst', 'short', 'config']
 
 
 def set_columns(cols=None):
@@ -638,6 +638,45 @@ def print_help(self, fh=None):
         fh = self.check_help(fh)
         OptionParser.print_help(self, fh)
 
+    def print_mdhelp(self, fh=None):
+        """Print help in MarkDown format"""
+        fh = self.check_help(fh)
+        result = []
+        if self.usage:
+            result.extend(["## Usage", '', '``%s``' % self.get_usage().replace("Usage: ", '').strip(), ''])
+        if self.description:
+            result.extend(["## Description", '', self.description, ''])
+
+        result.append(self.format_option_mdhelp())
+
+        mdhelptxt = '\n'.join(result)
+        if fh is None:
+            fh = sys.stdout
+        fh.write(mdhelptxt)
+
+    def format_option_mdhelp(self, formatter=None):
+        """ Formatting for help in rst format """
+        if not formatter:
+            formatter = self.formatter
+        formatter.store_option_strings(self)
+
+        res = []
+        titles = ["Option flag", "Option description"]
+
+        all_opts = [("Help options", self.option_list)] + \
+                   [(group.title, group.option_list) for group in self.option_groups]
+        for title, opts in all_opts:
+            values = []
+            res.extend(['## ' + title, ''])
+            for opt in opts:
+                if opt.help is not nohelp:
+                    values.append(['``%s``' % formatter.option_strings[opt], formatter.expand_default(opt)])
+
+            res.extend(mk_md_table(titles, map(list, zip(*values))))
+            res.append('')
+
+        return '\n'.join(res)
+
     def print_rsthelp(self, fh=None):
         """ Print help in rst format """
         fh = self.check_help(fh)