Refactor 1.0 docs with new toctree structure and inheritance

docs/pylib/contrib_readmes2docs.py

@@ -12,8 +12,11 @@ _DOCS_PATH = pathjoin(_EVENNIA_PATH, "docs")
 
 _SOURCE_DIR = pathjoin(_EVENNIA_PATH, "evennia", "contrib")
 _OUT_DIR = pathjoin(_DOCS_PATH, "source", "Contribs")
-_OUT_INDEX_FILE = pathjoin(_OUT_DIR, "Contrib-Overview.md")
+_OUT_INDEX_FILE = pathjoin(_OUT_DIR, "Contribs-Overview.md")
 
+_FILE_STRUCTURE = """{header}
+{categories}
+{footer}"""
 
 _CATEGORY_DESCS = {
     "base_systems": """
@@ -79,19 +82,19 @@ If you want to contribute yourself, see [here](Contributing)!
 """
 
 
-TOCTREE = """
-```{{toctree}}
+TOCTREE = """```{{toctree}}
+:maxdepth: 1
 
 {listing}
-```
-
-"""
+```"""
 
 CATEGORY = """
 ## {category}
 
 _{category_desc}_
 
+{toctree}
+
 {blurbs}
 
 
@@ -168,9 +171,9 @@ def readmes2docs(directory=_SOURCE_DIR):
 
     # build the index with blurbs
 
-    lines = [HEADER]
-    filenames = []
+    category_sections = []
     for category in sorted(categories):
+        filenames = []
         contrib_tups = categories[category]
         catlines = []
         for tup in sorted(contrib_tups, key=lambda tup: tup[0].lower()):
@@ -183,22 +186,23 @@ def readmes2docs(directory=_SOURCE_DIR):
                     code_location=tup[4]
                 )
             )
-            filenames.append(f"Contribs{sep}{tup[3]}")
-        lines.append(
+            filenames.append(f"{tup[3]}")
+        toctree = TOCTREE.format(listing="\n".join(filenames))
+        category_sections.append(
             CATEGORY.format(
                 category=category,
                 category_desc=_CATEGORY_DESCS[category].strip(),
-                blurbs="\n".join(catlines)
+                blurbs="\n".join(catlines),
+                toctree=toctree
             )
         )
-    lines.append(TOCTREE.format(
-        listing="\n  ".join(filenames))
+
+    text = _FILE_STRUCTURE.format(
+        header=HEADER,
+        categories="\n".join(category_sections),
+        footer=INDEX_FOOTER
     )
 
-    lines.append(INDEX_FOOTER)
-
-    text = "\n".join(lines)
-
     with open(_OUT_INDEX_FILE, 'w') as fil:
         fil.write(text)