add support for MarkDown ('md') output format for --list-software

boegel · boegel · commit abcd9d77c2d4 · 2022-12-05T17:07:08.000+01:00
diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py
@@ -634,6 +634,98 @@ def list_software(output_format=FORMAT_TXT, detailed=False, only_installed=False
     return generate_doc('list_software_%s' % output_format, [software, detailed])
 
 
+def list_software_md(software, detailed=True):
+    """
+    Return overview of supported software in MarkDown format
+
+    :param software: software information (structured like list_software does)
+    :param detailed: whether or not to return detailed information (incl. version, versionsuffix, toolchain info)
+    :return: multi-line string presenting requested info
+    """
+
+    lines = [
+        "# List of supported software",
+        '',
+        "EasyBuild supports %d different software packages (incl. toolchains, bundles):" % len(software),
+        '',
+    ]
+
+    # links to per-letter tables
+    letter_refs = ''
+    key_letters = nub(sorted(k[0].lower() for k in software.keys()))
+    letter_links = ' - '.join(['<a href="#' + x + '">' + x + '</a>' for x in ascii_lowercase if x in key_letters])
+    lines.extend([letter_links, ''])
+
+    letter = None
+    sorted_keys = sorted(software.keys(), key=lambda x: x.lower())
+    for key in sorted_keys:
+
+        # start a new subsection for each letter
+        if key[0].lower() != letter:
+
+            # subsection for new letter
+            letter = key[0].lower()
+            lines.extend([
+                '',
+                '<a anchor="%s"/>' % letter,
+                "### *%s*" % letter.upper(),
+                '',
+            ])
+
+            if detailed:
+                # quick links per software package
+                lines.extend([
+                    '',
+                    ' - '.join('<a href="#' + k + '">' + k + '</a>' for k in sorted_keys if k[0].lower() == letter),
+                    '',
+                ])
+
+        # append software to list, including version(suffix) & toolchain info if detailed info is requested
+        if detailed:
+            table_titles = ['version', 'toolchain']
+            table_values = [[], []]
+
+            # first determine unique pairs of version/versionsuffix
+            # we can't use LooseVersion yet here, since nub uses set and LooseVersion instances are not hashable
+            pairs = nub((x['version'], x['versionsuffix']) for x in software[key])
+
+            # check whether any non-empty versionsuffixes are in play
+            with_vsuff = any(vs for (_, vs) in pairs)
+            if with_vsuff:
+                table_titles.insert(1, 'versionsuffix')
+                table_values.insert(1, [])
+
+            # sort pairs by version (and then by versionsuffix);
+            # we sort by LooseVersion to obtain chronological version ordering,
+            # but we also need to retain original string version for filtering-by-version done below
+            sorted_pairs = sort_looseversions((LooseVersion(v), vs, v) for v, vs in pairs)
+
+            for _, vsuff, ver in sorted_pairs:
+                table_values[0].append('``%s``' % ver)
+                if with_vsuff:
+                    if vsuff:
+                        table_values[1].append('``%s``' % vsuff)
+                    else:
+                        table_values[1].append('')
+                tcs = [x['toolchain'] for x in software[key] if x['version'] == ver and x['versionsuffix'] == vsuff]
+                table_values[-1].append(', '.join('``%s``' % tc for tc in sorted(nub(tcs))))
+
+            lines.extend([
+                '',
+                '<a anchor="%s"/>' % key,
+                '### *%s*' % key,
+                '',
+                ' '.join(software[key][-1]['description'].split('\n')).lstrip(' '),
+                '',
+                "*homepage*: %s" % software[key][-1]['homepage'],
+                '',
+            ] + rst_title_and_table(None, table_titles, table_values))
+        else:
+            lines.append("* %s" % key)
+
+    return '\n'.join(lines)
+
+
 def list_software_rst(software, detailed=False):
     """
     Return overview of supported software in RST format
diff --git a/test/framework/docs.py b/test/framework/docs.py
@@ -263,6 +263,155 @@
       - EB_toytoy (easybuild.easyblocks.toytoy @ %(topdir)s/t/toytoy.py)
     - Toy_Extension (easybuild.easyblocks.generic.toy_extension @ %(topdir)s/generic/toy_extension.py)"""
 
+LIST_SOFTWARE_SIMPLE_TXT = """
+* GCC
+* gzip"""
+
+GCC_DESCR = "The GNU Compiler Collection includes front ends for C, C++, Objective-C, Fortran, Java, and Ada, "
+GCC_DESCR += "as well as libraries for these languages (libstdc++, libgcj,...)."
+GZIP_DESCR = "gzip (GNU zip) is a popular data compression program as a replacement for compress"
+
+LIST_SOFTWARE_DETAILED_TXT = """
+* GCC
+
+%(gcc_descr)s
+
+homepage: http://gcc.gnu.org/
+
+  * GCC v4.6.3: system
+
+* gzip
+
+%(gzip_descr)s
+
+homepage: http://www.gzip.org/
+
+  * gzip v1.4: GCC/4.6.3, system
+  * gzip v1.5: foss/2018a, intel/2018a
+""" % {'gcc_descr': GCC_DESCR, 'gzip_descr': GZIP_DESCR}
+
+LIST_SOFTWARE_SIMPLE_RST = """List of supported software
+==========================
+
+EasyBuild |version| supports 2 different software packages (incl. toolchains, bundles):
+
+:ref:`list_software_letter_g`
+
+
+.. _list_software_letter_g:
+
+*G*
+---
+
+* GCC
+* gzip"""
+
+LIST_SOFTWARE_DETAILED_RST = """List of supported software
+==========================
+
+EasyBuild |version| supports 2 different software packages (incl. toolchains, bundles):
+
+:ref:`list_software_letter_g`
+
+
+.. _list_software_letter_g:
+
+*G*
+---
+
+
+:ref:`list_software_GCC_205` - :ref:`list_software_gzip_442`
+
+
+.. _list_software_GCC_205:
+
+*GCC*
++++++
+
+%(gcc_descr)s
+
+*homepage*: http://gcc.gnu.org/
+
+=========    ==========
+version      toolchain 
+=========    ==========
+``4.6.3``    ``system``
+=========    ==========
+
+
+.. _list_software_gzip_442:
+
+*gzip*
+++++++
+
+%(gzip_descr)s
+
+*homepage*: http://www.gzip.org/
+
+=======    ===============================
+version    toolchain                      
+=======    ===============================
+``1.4``    ``GCC/4.6.3``, ``system``      
+``1.5``    ``foss/2018a``, ``intel/2018a``
+=======    ===============================
+""" % {'gcc_descr': GCC_DESCR, 'gzip_descr': GZIP_DESCR}
+
+LIST_SOFTWARE_SIMPLE_MD = """# List of supported software
+
+EasyBuild supports 2 different software packages (incl. toolchains, bundles):
+
+<a href="#g">g</a>
+
+
+<a anchor="g"/>
+### *G*
+
+* GCC
+* gzip"""
+
+LIST_SOFTWARE_DETAILED_MD = """# List of supported software
+
+EasyBuild supports 2 different software packages (incl. toolchains, bundles):
+
+<a href="#g">g</a>
+
+
+<a anchor="g"/>
+### *G*
+
+
+<a href="#GCC">GCC</a> - <a href="#gzip">gzip</a>
+
+
+<a anchor="GCC"/>
+### *GCC*
+
+%(gcc_descr)s
+
+*homepage*: http://gcc.gnu.org/
+
+=========    ==========
+version      toolchain 
+=========    ==========
+``4.6.3``    ``system``
+=========    ==========
+
+
+<a anchor="gzip"/>
+### *gzip*
+
+%(gzip_descr)s
+
+*homepage*: http://www.gzip.org/
+
+=======    ===============================
+version    toolchain                      
+=======    ===============================
+``1.4``    ``GCC/4.6.3``, ``system``      
+``1.5``    ``foss/2018a``, ``intel/2018a``
+=======    ===============================
+""" % {'gcc_descr': GCC_DESCR, 'gzip_descr': GZIP_DESCR}
+
 
 class DocsTest(EnhancedTestCase):
 
@@ -376,107 +525,14 @@ def test_list_software(self):
         }
         init_config(build_options=build_options)
 
-        expected = '\n'.join([
-            '',
-            '* GCC',
-            '* gzip',
-        ])
-        self.assertEqual(list_software(output_format='txt'), expected)
-
-        expected = re.compile('\n'.join([
-            r'',
-            r'\* GCC',
-            r'',
-            r"The GNU Compiler Collection .*",
-            r'',
-            r'homepage: http://gcc.gnu.org/',
-            r'',
-            r'  \* GCC v4.6.3: system',
-            r'',
-            r'\* gzip',
-            r'',
-            r"gzip \(GNU zip\) is .*",
-            r'',
-            r'homepage: http://www.gzip.org/',
-            r'',
-            r"  \* gzip v1.4: GCC/4.6.3, system",
-            r"  \* gzip v1.5: foss/2018a, intel/2018a",
-            '',
-        ]))
-        txt = list_software(output_format='txt', detailed=True)
-        self.assertTrue(expected.match(txt), "Pattern '%s' found in: %s" % (expected.pattern, txt))
+        self.assertEqual(list_software(output_format='txt'), LIST_SOFTWARE_SIMPLE_TXT)
+        self.assertEqual(list_software(output_format='txt', detailed=True), LIST_SOFTWARE_DETAILED_TXT)
 
-        expected = '\n'.join([
-            "List of supported software",
-            "==========================",
-            '',
-            "EasyBuild |version| supports 2 different software packages (incl. toolchains, bundles):",
-            '',
-            ':ref:`list_software_letter_g`',
-            '',
-            '',
-            '.. _list_software_letter_g:',
-            '',
-            '*G*',
-            '---',
-            '',
-            '* GCC',
-            '* gzip',
-        ])
-        self.assertEqual(list_software(output_format='rst'), expected)
-
-        expected = re.compile('\n'.join([
-            r"List of supported software",
-            r"==========================",
-            r'',
-            r"EasyBuild \|version\| supports 2 different software packages \(incl. toolchains, bundles\):",
-            r'',
-            r':ref:`list_software_letter_g`',
-            r'',
-            r'',
-            r'.. _list_software_letter_g:',
-            r'',
-            r'\*G\*',
-            r'---',
-            r'',
-            r'',
-            r':ref:`list_software_GCC_205` - :ref:`list_software_gzip_442`',
-            r'',
-            r'',
-            r'\.\. _list_software_GCC_205:',
-            r'',
-            r'\*GCC\*',
-            r'\+\+\+\+\+',
-            r'',
-            r'The GNU Compiler Collection .*',
-            r'',
-            r'\*homepage\*: http://gcc.gnu.org/',
-            r'',
-            r'=========    ==========',
-            r'version      toolchain ',
-            r'=========    ==========',
-            r'``4.6.3``    ``system``',
-            r'=========    ==========',
-            r'',
-            r'',
-            r'\.\. _list_software_gzip_442:',
-            r'',
-            r'\*gzip\*',
-            r'\+\+\+\+\+\+',
-            r'',
-            r'gzip \(GNU zip\) is a popular .*',
-            r'',
-            r'\*homepage\*: http://www.gzip.org/',
-            r'',
-            r'=======    ===============================',
-            r'version    toolchain                      ',
-            r'=======    ===============================',
-            r'``1.4``    ``GCC/4.6.3``, ``system``      ',
-            r'``1.5``    ``foss/2018a``, ``intel/2018a``',
-            r'=======    ===============================',
-        ]))
-        txt = list_software(output_format='rst', detailed=True)
-        self.assertTrue(expected.match(txt), "Pattern '%s' found in: %s" % (expected.pattern, txt))
+        self.assertEqual(list_software(output_format='rst'), LIST_SOFTWARE_SIMPLE_RST)
+        self.assertEqual(list_software(output_format='rst', detailed=True), LIST_SOFTWARE_DETAILED_RST)
+
+        self.assertEqual(list_software(output_format='md'), LIST_SOFTWARE_SIMPLE_MD)
+        self.assertEqual(list_software(output_format='md', detailed=True), LIST_SOFTWARE_DETAILED_MD)
 
         # GCC/4.6.3 is installed, no gzip module installed
         txt = list_software(output_format='txt', detailed=True, only_installed=True)
