use separate pages in software overview (for EasyBuild v4.9.2)

.github/workflows/test.yml

@@ -25,8 +25,8 @@ jobs:
           ignore_words_list: atleast,ninjs,simpy,proovread,namd,precice,crate,ake
           # filter out
           #   docs/js/asciinema-player-2.6.1.js as it is not markdown
-          #   version-specific/supported-software.md as the software descriptions have spelling errors
-          skip: './docs/js/asciinema-player-2.6.1.js,./docs/version-specific/supported-software.md,./docs/release-notes.md'
+          #   version-specific/supported-software/* as the software descriptions have spelling errors
+          skip: './docs/js/asciinema-player-2.6.1.js,./docs/version-specific/supported-software/*,./docs/version-specific/supported-software/*/*.md,./docs/release-notes.md'
 
       - name: check internal links
         run: python ./.github/workflows/link_check.py

docs/version-specific/index.md

@@ -8,7 +8,7 @@
 * [List of available easyblocks](easyblocks.md)
 * [List of available toolchain options](toolchain-opts.md)
 * [List of known toolchains](toolchains.md)
-* [List of supported software](supported-software.md)
+* [List of supported software](supported-software/index.md)
 * [Overview of EasyBuild configuration options](eb-help.md)
 * [Overview of generic easyblocks](generic-easyblocks.md)
 * [Templates available for easyconfig files](easyconfig-templates.md)

docs/version-specific/software-markdown-pages.py

@@ -0,0 +1,132 @@
+import argparse
+import json
+import shutil
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+
+MKDOCS_SEARCH_PRIORITY = """---
+search:
+  boost: 0.5
+---
+"""
+
+
+def generate_quick_links_line(chars, level, current=None):
+    """
+    Generate links to index page for each character
+    :param characters: Initial characters to generate links for
+    """
+    up = '/'.join(['..'] * level) or '.'
+    links = []
+    if level > 0:
+        links.append(f"[(all)]({up}/index.md)")
+    for char in chars:
+        if char == current:
+            links.append(f'*{char}*')
+        else:
+            links.append(f"[{char}]({up}/{char}/index.md)")
+    links_txt = ' - '.join(links)
+    return f"*(quick links: {links_txt})*\n\n"
+
+
+def output_markdown(processed, output_base_path):
+    """
+    Output markdown pages (index and per letter directories, each with an index and page per software)
+    :param processed: Processed data to output (dictionary - letter -> software -> list of versions)
+    :param output_base_path: Pathlib object for base path of output
+    """
+    pkg_cnt = sum(len(v) for v in processed.values())
+    letters = sorted(processed.keys())
+
+    with open(output_base_path / 'index.md', 'w') as top_page:
+        top_page.write(MKDOCS_SEARCH_PRIORITY)
+        top_page.write("# List of supported software\n\n")
+        top_page.write(generate_quick_links_line(letters, 0))
+        top_page.write(f"EasyBuild supports {pkg_cnt} different software packages (incl. toolchains, bundles):\n\n")
+
+        for letter in processed:
+            top_page.write(f" * [{letter}]({letter}/index.md)\n")
+
+            letter_dir = output_base_path / letter
+            letter_dir.mkdir()
+            with open(letter_dir / 'index.md', 'w') as letter_page:
+                letter_page.write(MKDOCS_SEARCH_PRIORITY)
+                letter_page.write(f"# List of supported software ({letter})\n\n")
+                letter_page.write(generate_quick_links_line(letters, 1, current=letter) + "\n\n")
+
+                for software in processed[letter]:
+                    top_page.write(f"    * [{software}]({letter}/{software}.md)\n")
+                    letter_page.write(f" * [{software}]({software}.md)\n")
+
+                    versionsuffix = any(v['versionsuffix'] for v in processed[letter][software])
+
+                    with open(letter_dir / f'{software}.md', 'w') as software_page:
+                        software_page.write(MKDOCS_SEARCH_PRIORITY)
+                        software_page.write(f"# {software}\n\n")
+                        software_page.write(f"{processed[letter][software][0]['description']}\n\n")
+                        software_page.write(f"*homepage*: <{processed[letter][software][0]['homepage']}>\n\n")
+
+                        if versionsuffix:
+                            software_page.write("version | versionsuffix | toolchain\n")
+                            software_page.write("--------|---------------|----------\n")
+                        else:
+                            software_page.write("version | toolchain\n")
+                            software_page.write("--------|----------\n")
+
+                        for version in processed[letter][software]:
+                            software_page.write(f"``{version['version']}`` | ")
+                            if versionsuffix:
+                                if version['versionsuffix']:
+                                    software_page.write(f"``{version['versionsuffix']}``")
+                                software_page.write(" | ")
+                            software_page.write(f"``{version['toolchain']}``\n")
+
+                        software_page.write("\n\n" + generate_quick_links_line(letters, 1))
+
+                letter_page.write("\n\n" + generate_quick_links_line(letters, 1, current=letter))
+
+        top_page.write("\n\n" + generate_quick_links_line(letters, 0))
+
+
+def generate_markdown_pages(jsonfile, output_base, delete_existing):
+    """
+    Generate markdown
+    :param jsonfile: input file (json file)
+    :param output_base: base directory for output files
+    :param delete_existing: delete the output directory (if it exists)
+    """
+    if jsonfile is None:
+        sys.stderr.write("ERROR: No input JSON file specified, it is required!\n")
+        sys.exit(1)
+
+    with open(jsonfile) as f:
+        data = json.load(f)
+
+    processed = defaultdict(lambda: defaultdict(list))
+    for software in data:
+        initial = software['name'][0].lower()
+        if initial.isnumeric():
+            initial = '0'
+        processed[initial][software['name']].append(software)
+
+    output_base_path = Path(output_base)
+
+    if delete_existing and output_base_path.exists() and output_base_path.is_dir():
+        shutil.rmtree(output_base_path)
+
+    output_base_path.mkdir(parents=True)
+    output_markdown(processed, output_base_path)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(prog='Software Markdown Pages',
+                                     description='Generate Markdown pages of software from JSON file')
+    parser.add_argument('-j', '--jsonfile', default=None, help='Input JSON file')
+    parser.add_argument('-o', '--output-base', default='output', help='Base directory for output files')
+    parser.add_argument('--delete-existing-output', action='store_true',
+                        help='Delete output base directory (if it exists)')
+    args = parser.parse_args()
+
+    generate_markdown_pages(args.jsonfile, args.output_base, args.delete_existing_output)