TL: first step toward cross-reference links

Author: tlunet

CONTRIBUTING.md

@@ -12,4 +12,4 @@ Additionally, a _few_ rules are set to enforce code readability, consistency and
 Others are specific conventions chosen for the pySDC library, that may follow Python standards (or not ...), detailed in the [naming conventions page](./docs/contrib/03_naming_conventions.md).
 
 Finally, while `pySDC` provides many base functionalities that implement classical flavors of SDC, it also allows problem-specific applications through Object-Oriented Programming (OOP) and the implementation of custom inherited classes.
-This follows a specific OOP framework, for which more details are given [here](.(docs/contrib/../../docs/contrib/04_custom_implementations.md)).
+This follows a specific OOP framework, for which more details are given [here](./docs/contrib/04_custom_implementations.md).

docs/convert_markdown.py

@@ -9,6 +9,7 @@
 import glob
 import json
 import m2r2
+import numpy as np
 
 mdFiles = [
     'README.md',
@@ -19,14 +20,53 @@
 
 docSources = 'docs/source'
 
+counter = np.array(0)
+
 with open('docs/emojis.json') as f:
     emojis = set(json.load(f).keys())
 
-def convert(md):
-    rst = m2r2.parse_from_file(md, parse_relative_links=True)
+def wrappEmojis(rst):
     for emoji in emojis:
         rst = rst.replace(emoji, f'|{emoji}|')
+    return rst
+
+def addSectionRefs(rst, baseName):
+    sections = {}
+    lines = rst.splitlines()
+    # Search for sections in rst file
+    for i in range(len(lines)-2):
+        conds = [
+            len(lines[i+1]) and lines[i+1][0] in ['=', '-', '^', '"'],
+            lines[i+2] == lines[i-1] == '',
+            len(lines[i]) == len(lines[i+1])]
+        if all(conds):
+            sections[i] = lines[i]
+    # Add unique references before each section
+    for i, title in sections.items():
+        ref = '-'.join([elt for elt in title.lower().split(' ') if elt != ''])
+        for char in ['#', "'", '^', '°', '!']:
+            ref = ref.replace(char, '')
+        ref = f'{baseName}/{ref}'
+        lines[i] = f'.. _{ref}:\n\n'+lines[i]
+    # Returns all concatenated lines
+    return '\n'.join(lines)
+
+def completeRefLinks(rst, baseName):
+    i = 0
+    while i != -1:
+        i = rst.find(':ref:`', i)
+        if i != -1:
+            iLink = rst.find('<', i)
+            rst = rst[:iLink+1]+f'{baseName}/'+rst[iLink+1:]
+            i += 6
+    return rst
+
+def convert(md):
     baseName = os.path.splitext(md)[0]
+    rst = m2r2.parse_from_file(md, parse_relative_links=True)
+    rst = wrappEmojis(rst)
+    rst = addSectionRefs(rst, baseName)
+    rst = completeRefLinks(rst, baseName)
     with open(f'{docSources}/{baseName}.rst', 'w') as f:
         f.write(rst)
     print(f'Converted {md} to {docSources}/{baseName}.rst')

docs/source/conf.py

@@ -107,7 +107,7 @@
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #
-# add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.