Merge pull request #4155 from branfosj/docs

fix MarkDown formatting in autogenerated documentation
easybuilders · Jan 4, 2023 · 6adfa5d · 6adfa5d
2 parents e784549 + 9f9810f
commit 6adfa5d
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 25 deletions.
diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py
@@ -796,7 +796,7 @@ def list_software_md(software, detailed=True):
 
     # links to per-letter tables
     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])
+    letter_links = ' - '.join(['[' + x + '](#' + x + ')' for x in ascii_lowercase if x in key_letters])
     lines.extend([letter_links, ''])
 
     letter = None
@@ -810,16 +810,15 @@ def list_software_md(software, detailed=True):
             letter = key[0].lower()
             lines.extend([
                 '',
-                '<a anchor="%s"/>' % letter,
-                "### *%s*" % letter.upper(),
+                "### %s" % letter.upper(),
                 '',
             ])
 
             if detailed:
                 # quick links per software package
                 lines.extend([
                     '',
-                    ' - '.join('<a href="#%s">%s</a>' % (k.lower(), k) for k in sorted_keys if k[0].lower() == letter),
+                    ' - '.join('[%s](#%s)' % (k, k.lower()) for k in sorted_keys if k[0].lower() == letter),
                     '',
                 ])
 
@@ -855,12 +854,11 @@ def list_software_md(software, detailed=True):
 
             lines.extend([
                 '',
-                '<a anchor="%s"/>' % key.lower(),
-                '### *%s*' % key,
+                '### %s' % key,
                 '',
                 ' '.join(software[key][-1]['description'].split('\n')).lstrip(' '),
                 '',
-                "*homepage*: %s" % software[key][-1]['homepage'],
+                "*homepage*: <%s>" % software[key][-1]['homepage'],
                 '',
             ] + md_title_and_table(None, table_titles, table_values))
         else:
@@ -1261,7 +1259,7 @@ def gen_easyblocks_overview_md(package_name, path_to_examples, common_params=Non
     eb_links = []
     for eb_class in sorted(eb_classes, key=lambda c: c.__name__):
         eb_name = eb_class.__name__
-        eb_links.append("<a href='#" + eb_name.lower() + "'>" + eb_name + "</a>")
+        eb_links.append("[" + eb_name + "](#" + eb_name.lower() + ")")
 
     heading = [
         "# Overview of generic easyblocks",
@@ -1383,6 +1381,7 @@ def gen_easyblock_doc_section_md(eb_class, path_to_examples, common_params, doc_
 
     if custom:
         doc.append("### Customised steps in ``" + classname + "`` easyblock")
+        doc.append('')
         doc.extend(custom)
         doc.append('')
 

diff --git a/test/framework/docs.py b/test/framework/docs.py
@@ -363,11 +363,10 @@
 
 EasyBuild supports 2 different software packages (incl. toolchains, bundles):
 
-<a href="#g">g</a>
+[g](#g)
 
 
-<a anchor="g"/>
-### *G*
+### G
 
 * GCC
 * gzip"""
@@ -376,33 +375,30 @@
 
 EasyBuild supports 2 different software packages (incl. toolchains, bundles):
 
-<a href="#g">g</a>
+[g](#g)
 
 
-<a anchor="g"/>
-### *G*
+### G
 
 
-<a href="#gcc">GCC</a> - <a href="#gzip">gzip</a>
+[GCC](#gcc) - [gzip](#gzip)
 
 
-<a anchor="gcc"/>
-### *GCC*
+### GCC
 
 %(gcc_descr)s
 
-*homepage*: http://gcc.gnu.org/
+*homepage*: <http://gcc.gnu.org/>
 
 version  |toolchain
 ---------|----------
 ``4.6.3``|``system``
 
-<a anchor="gzip"/>
-### *gzip*
+### gzip
 
 %(gzip_descr)s
 
-*homepage*: http://www.gzip.org/
+*homepage*: <http://www.gzip.org/>
 
 version|toolchain
 -------|-------------------------------
@@ -526,7 +522,7 @@ def test_gen_easyblocks_overview(self):
                     self.assertTrue(name in ebdoc)
                     names.append(name)
 
-        toc = ["<a href='#" + n.lower() + "'>" + n + "</a>" for n in sorted(set(names))]
+        toc = ["\\[" + n + "\\]\\(#" + n.lower() + "\\)" for n in sorted(set(names))]
         pattern = " - ".join(toc)
         regex = re.compile(pattern)
         self.assertTrue(re.search(regex, ebdoc), "Pattern %s found in %s" % (regex.pattern, ebdoc))
@@ -746,7 +742,7 @@ def test_avail_easyconfig_constants(self):
             r"^Constants that can be used in easyconfigs",
             r"^\s*ARCH: .* \(CPU architecture of current system \(aarch64, x86_64, ppc64le, ...\)\)",
             r"^\s*OS_PKG_OPENSSL_DEV: \('openssl-devel', 'libssl-dev', 'libopenssl-devel'\) "
-            r"\(OS packages providing openSSL developement support\)",
+            r"\(OS packages providing openSSL development support\)",
         ]
 
         txt = avail_easyconfig_constants()
@@ -763,7 +759,7 @@ def test_avail_easyconfig_constants(self):
             r"^# Constants that can be used in easyconfigs",
             r"^``ARCH``\s*\|``.*``\s*\|CPU architecture of current system \(aarch64, x86_64, ppc64le, ...\)$",
             r"^``OS_PKG_OPENSSL_DEV``\s*\|``\('openssl-devel', 'libssl-dev', 'libopenssl-devel'\)``\s*\|"
-            r"OS packages providing openSSL developement support$",
+            r"OS packages providing openSSL development support$",
         ]
         txt_md = avail_easyconfig_constants(output_format='md')
         for pattern in md_patterns:
@@ -774,7 +770,7 @@ def test_avail_easyconfig_constants(self):
             r"^Constants that can be used in easyconfigs\n-{41}",
             r"^``ARCH``\s*``.*``\s*CPU architecture of current system \(aarch64, x86_64, ppc64le, ...\)$",
             r"^``OS_PKG_OPENSSL_DEV``\s*``\('openssl-devel', 'libssl-dev', 'libopenssl-devel'\)``\s*"
-            r"OS packages providing openSSL developement support$",
+            r"OS packages providing openSSL development support$",
         ]
         txt_rst = avail_easyconfig_constants(output_format='rst')
         for pattern in rst_patterns: