Add doc-contribution page, toctree-creation mechanism

docs/pylib/copy_from_wiki.py

@@ -15,7 +15,7 @@ We also need to build the toc-tree and should do so automatically for now.
 
 import glob
 import re
-import datetime 
+import datetime
 
 _RE_MD_LINK = re.compile(r"\[(?P<txt>[\w -\[\]]+?)\]\((?P<url>.+?)\)", re.I + re.S + re.U)
 _RE_REF_LINK = re.compile(r"\[[\w -\[\]]*?\]\(.+?\)", re.I + re.S + re.U)
@@ -32,13 +32,13 @@ _INDEX_PREFIX = f"""
 
 # VERSION WARNING
 
-> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the 
+> This is the experimental static v0.9 documentation of Evennia, _automatically_ generated from the
 > [evennia wiki](https://github.com/evennia/evennia/wiki/) at {datetime.datetime.now()}.
-> There are known conversion issues which  will _not_ be addressed in this version - refer to 
+> There are known conversion issues which  will _not_ be addressed in this version - refer to
 > the original wiki if you have trouble.
 >
 > Manual conversion and cleanup will instead happen during development of the upcoming v1.0
-> version of this static documentation. 
+> version of this static documentation.
 
 """
 
@@ -202,7 +202,6 @@ def _sub_link(match):
     return f"[{txt}]({url})"
 
 def create_toctree(files):
-
     with open("../source/toc.md", "w") as fil:
         fil.write("# Toc\n")
 
@@ -221,7 +220,7 @@ def convert_links(files, outdir):
 
     for inpath in files:
 
-        is_index = False 
+        is_index = False
         outfile = inpath.rsplit('/', 1)[-1]
         if outfile == "Home.md":
             outfile = "index.md"
@@ -235,7 +234,7 @@ def convert_links(files, outdir):
             text = fil.read()
 
             if is_index:
-                text = _INDEX_PREFIX + text 
+                text = _INDEX_PREFIX + text
                 lines = text.split("\n")
                 lines = (lines[:-11]
                          + [" - The [TOC](toc) lists all regular documentation pages.\n\n"]
@@ -256,6 +255,6 @@ def convert_links(files, outdir):
             fil.write(text)
 
 if __name__ == "__main__":
-
-    create_toctree(_INFILES)
-    convert_links(_INFILES, _OUTDIR)
+    print("This should not be run on develop files, it would overwrite changes.")
+    # create_toctree(_INFILES)
+    # convert_links(_INFILES, _OUTDIR)

docs/pylib/create_toctree.py

@@ -0,0 +1,40 @@
+"""
+Build a TOC-tree; Sphinx requires it and this makes it easy to just
+add/build/link new files without needing to explicitly add it to a toctree
+directive somewhere.
+
+"""
+
+import glob
+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")
+
+
+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]
+
+    with open(_TOC_FILE, "w") as fil:
+        fil.write("# Toc\n")
+
+        for ref in _FILENAMES:
+
+            if ref == "toc":
+                continue
+
+            linkname = ref.replace("-", " ")
+            fil.write(f"\n- [{linkname}]({ref}.md)")
+
+
+if __name__ == "__main__":
+    create_toctree()