Fixing doc deploy

docs/deploy.py

@@ -3,21 +3,35 @@ Deploy to github, from github Action. This is run after the docs have finished b
 documentation branches will be available in build/html/* at this point. We need to copy those
 contents to the root of the repo.
 
+This can be tested with `make release` or `make deploy` and require git push rights to
+the evennia repo. Use DISABLE_GIT_PUSH for local testing - git-pushing from local can cause
+clashes upstream.
+
+We will look in source/conf.py for the `.latest_version` string and `.legacy_versions` list,
+this allows us to skip deleting legacy docs (which may be ever harder to build) while correctly
+symlinking to the current 'latest' documentation.
+
 This is assumed to be executed from inside the docs/ folder.
+
 """
 
 import glob
+import importlib
 import os
 import subprocess
 import sys
 
-# branches that should not be rebuilt anymore (all others are considered active)
-legacy_branches = ["0.9.5"]
-# the branch pointed to by the 'latest' symlink
-latest_branch = "0.9.5"
+# set for local testing
+DISABLE_GIT_PUSH = False
 
 
 def deploy():
+    """Perform the deploy of the built Evennia documentation to the gh-pages branch."""
+
+    conf_file = importlib.machinery.SourceFileLoader("conf", "source/conf.py").load_module()
+
+    latest_version = conf_file.latest_version
+    legacy_versions = conf_file.legacy_versions
 
     if subprocess.call(["git", "status", "--untracked=no", "--porcelain"]):
         print(
@@ -30,33 +44,43 @@ def deploy():
     os.system("git fetch")
     os.system("git checkout gh-pages")
 
+    os.system("pwd")
+    os.system("ls")
+
+    names_to_skip = legacy_versions + ["build"]
+
     for file_path in glob.glob("*"):
         # run from inside the docs/ dir
         # delete old but active doc branches
 
-        _, *filename = file_path.rsplit("/", 1)
-
-        if filename and filename[0] in legacy_branches:
+        if file_path in names_to_skip:
             # skip deleting the legacy brancehs
             continue
         else:
             # we want to delete both active branches and old symlinks
-            print("remove file_path:", file_path)
             os.system(f"rm -Rf {file_path}")
+            print(f"removed file_path: {file_path}")
 
     # copy built branches to current dir
+    os.system("ls")
+
     os.system("cp -Rf build/html/* .")
+
+    os.system("ls")
+
     # symlink to latest and link its index to the root
-    os.system(f"ln -s {latest_branch} latest")
-    os.system(f"ln -s {latest_branch}/index.html .")
+    os.system(f"ln -s {latest_version} latest")
+    os.system(f"ln -s {latest_version}/index.html .")
 
-    # docs/build is in .gitignore so will be skipped
-    os.system("git add .")
-    os.system('git commit -a -m "Updated HTML docs."')
-    os.system("git push origin gh-pages")
+    os.system("ls")
 
-    # get back to previous branch
-    os.system("git checkout .")
+    if not DISABLE_GIT_PUSH:
+        print("committing and pushing docs ...")
+        os.system("git add .")  # docs/build is in .gitignore so will be skipped
+        os.system('git commit -a -m "Updated HTML docs."')
+        os.system("git push origin gh-pages")
+    else:
+        print("Skipped git push.")
 
     print("Deployed to https:// evennia.github.io/evennia/")
 

docs/source/conf.py

@@ -59,11 +59,15 @@ smv_outputdir_format = "{config.release}"
 # don't make docs for tags
 smv_tag_whitelist = r"^$"
 
-# used to fill in versioning.html links for versions that are not actually built
+# used to fill in versioning.html links for versions that are not actually built.
+# These are also read from the deploy.py script. These are also the names of
+# the folders built in the gh-pages evennia branch, under docs/.
+latest_version = "0.9.5"
 legacy_versions = ["0.9.5"]
 
 
 def add_legacy_versions_to_html_page_context(app, pagename, templatename, context, doctree):
+    # this is read by versioning.html template (sidebar)
     LVersion = namedtuple("legacy_version", ["release", "name", "url"])
     context["legacy_versions"] = [
         LVersion(release=f"{vers}", name=f"v{vers}", url=f"../{vers}/index.html")