Refactor 1.0 docs with new toctree structure and inheritance

docs/pylib/auto_link_remapper.py

@@ -38,18 +38,18 @@ TXT_REMAPS = {
 }
 URL_REMAPS = {
     "Developer-Central": "Components/Components-Overview",
-    "Tutorials": "Howto/Howto-Overview",
-    "../Howto/Starting/Directory-Overview": "Gamedir-Overview",
-    "Howto/Starting/Directory-Overview": "Gamedir-Overview",
-    "Starting/Directory-Overview": "Gamedir-Overview",
+    "Tutorials": "Howtos/Howtos-Overview",
+    "../Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
+    "Howtos/Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
+    "Beginner-Tutorial/Directory-Overview": "Gamedir-Overview",
     "Directory-Overview": "Gamedir-Overview",
     "../Setup/Getting-Started": "Setup-Quickstart",
     "Setup/Getting-Started": "Setup-Quickstart",
     "Getting-Started": "Setup-Quickstart",
-    "First-Steps-Coding": "Starting-Part1",
-    "../Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
-    "Howto/Starting/Adding-Command-Tutorial": "Adding-Commands",
-    "Starting/Adding-Command-Tutorial": "Adding-Commands",
+    "First-Steps-Coding": "Beginner-Tutorial-Part1",
+    "../Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
+    "Howtos/Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
+    "Beginner-Tutorial/Adding-Command-Tutorial": "Adding-Commands",
     "Adding-Command-Tutorial": "Adding-Commands",
     "CmdSet": "Command-Sets",
     "Spawner": "Prototypes",
@@ -248,26 +248,26 @@ def auto_link_remapper(no_autodoc=False):
             print(f"  ORPHANED DOC: no refs found to {src_url}.md")
 
     # write tocfile
-    with open(_TOC_FILE, "w") as fil:
-        fil.write("```{toctree}\n")
+    # with open(_TOC_FILE, "w") as fil:
+    #     fil.write("```{toctree}\n")
 
-        if not no_autodoc:
-            fil.write("- [API root](api/evennia-api.rst)")
+    #     if not no_autodoc:
+    #         fil.write("- [API root](api/evennia-api.rst)")
 
-        for ref in sorted(toc_map.values()):
+    #     for ref in sorted(toc_map.values()):
 
-            if ref == "toc":
-                continue
+    #         if ref == "toc":
+    #             continue
 
-            # if not "/" in ref:
-            #     ref = "./" + ref
+    #         # if not "/" in ref:
+    #         #     ref = "./" + ref
 
-            # linkname = ref.replace("-", " ")
-            fil.write(f"\n{ref}")  # - [{linkname}]({ref})")
+    #         # linkname = ref.replace("-", " ")
+    #         fil.write(f"\n{ref}")  # - [{linkname}]({ref})")
 
-        # we add a self-reference so the toc itself is also a part of a toctree
-        fil.write("\n```\n\n```{toctree}\n  :hidden:\n\ntoc\n```")
-        print("  -- File toc.md updated.")
+    #     # we add a self-reference so the toc itself is also a part of a toctree
+    #     fil.write("\n```\n\n```{toctree}\n  :hidden:\n\ntoc\n```")
+    #     print("  -- File toc.md updated.")
 
     print("  -- Auto-Remapper finished.")
 

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)
 

docs/pylib/update_dynamic_pages.py

@@ -17,7 +17,7 @@ def update_changelog():
     """
 
     sourcefile = pathjoin(ROOTDIR, "CHANGELOG.md")
-    targetfile = pathjoin(DOCSRCDIR, "Setup", "Changelog.md")
+    targetfile = pathjoin(DOCSRCDIR, "Coding", "Changelog.md")
 
     with open(sourcefile) as fil:
         txt = fil.read()