diff --git a/docs/pylib/create_toctree.py b/docs/pylib/create_toctree.py
index 86b752955b..65b6ef708e 100644
--- a/docs/pylib/create_toctree.py
+++ b/docs/pylib/create_toctree.py
@@ -5,10 +5,10 @@ directive somewhere.
 
 """
 
-import glob
+import re
+from pathlib import Path
 from os.path import abspath, dirname, join as pathjoin, sep
 
-_SOURCEDIR = "../source/"
 _IGNORE_FILES = []
 _SOURCE_DIR = pathjoin(dirname(dirname(abspath(__file__))), "source")
 _TOC_FILE = pathjoin(_SOURCE_DIR, "toc.md")
@@ -18,16 +18,61 @@ def create_toctree():
     """
     Create source/toc.md file
     """
-    _INFILES = [path for path in glob.glob(_SOURCE_DIR + sep + "*.md")
-                if path.rsplit('/', 1)[-1] not in _IGNORE_FILES]
-    # split out the name and remove the .md extension
-    _FILENAMES = [path.rsplit("/", 1)[-1] for path in sorted(_INFILES)]
-    _FILENAMES = [path.split(".", 1)[0] for path in _FILENAMES]
 
+    docref_map = {}
+
+    for path in Path(_SOURCE_DIR).rglob("*.md"):
+        # find the source/ part of the path and strip it out
+        # support nesting of 3 within source/ dir
+        # from pudb import debugger;debugger.Debugger().set_trace()
+        fname = path.name
+        if fname in _IGNORE_FILES:
+            # this is the name including .md
+            continue
+        ind = path.parts[-4:].index("source")
+        pathparts = path.parts[-4 + 1 + ind:]
+        url = "/".join(pathparts)
+        fname = fname.rsplit(".", 1)[0]
+        if fname in docref_map:
+            raise RuntimeError(f"'{url}' and '{docref_map[fname]}': Auto-link correction does not "
+                               "accept doc-files with the same name, even in different folders.")
+        docref_map[fname] = url
+
+    ref_regex = re.compile(r"\[(?P<txt>[\w -\[\]]+?)\]\((?P<url>"
+                           + r"|".join(docref_map)
+                           + r")\)", re.I + re.S + re.U)
+
+    def _sub(match):
+        grpdict = match.groupdict()
+        txt, url = grpdict['txt'], grpdict['url']
+        fname, *part = url.rsplit("/", 1)
+        fname = part[0] if part else fname
+        fname = fname.rsplit(".", 1)[0]
+        urlout = docref_map.get(fname, url)
+        if url != urlout:
+            print(f"Remapped link [{txt}]({url}) -> [{txt}]({urlout})")
+        return f"[{txt}]({urlout})"
+
+    # replace / correct links in all files
+    count = 0
+    for path in Path(_SOURCE_DIR).rglob("*.md"):
+        with open(path, 'r') as fil:
+            intxt = fil.read()
+            outtxt = ref_regex.sub(_sub, intxt)
+        if intxt != outtxt:
+            with open(path, 'w') as fil:
+                fil.write(outtxt)
+            count += 1
+            print(f"Auto-relinked links in {path.name}")
+
+    if count > 0:
+        print(f"Auto-corrected links in {count} documents.")
+
+    # write tocfile
     with open(_TOC_FILE, "w") as fil:
         fil.write("# Toc\n")
 
-        for ref in _FILENAMES:
+        for ref  in sorted(docref_map.values()):
 
             if ref == "toc":
                 continue
@@ -35,6 +80,5 @@ def create_toctree():
             linkname = ref.replace("-", " ")
             fil.write(f"\n- [{linkname}]({ref}.md)")
 
-
 if __name__ == "__main__":
     create_toctree()
diff --git a/docs/pylib/fmtwidth.py b/docs/pylib/fmtwidth.py
index 574a5709ab..d6de0a7900 100644
--- a/docs/pylib/fmtwidth.py
+++ b/docs/pylib/fmtwidth.py
@@ -5,7 +5,7 @@
 Format given files to a max width.
 
 Usage:
-    python fmtwidth.py --width 79 ../source/*.md
+    python fmtwidth.py --width 79 ../source/**.md
 
 """
 import glob
@@ -23,7 +23,7 @@ if __name__ == "__main__":
 
     args = parser.parse_args()
 
-    filepaths = glob.glob(args.files)
+    filepaths = glob.glob(args.files, recursive=True)
     width = args.width
 
     wrapper = textwrap.TextWrapper(