Testing alternative versioning

docs/Makefile

@@ -125,7 +125,6 @@ quickstrict:
 # we build index directly for the current branch
 local:
 	make _check-env
-	make clean
 	make _autodoc-index
 	make _html-build
 	@echo ""
@@ -147,7 +146,6 @@ mv-index:
 
 mv-local:
 	make _multiversion-check-env
-	make clean
 	make _multiversion-build
 	@echo ""
 	@echo "Documentation built (multiversion + autodocs)."
@@ -160,7 +158,6 @@ deploy:
 	@echo "Documentation deployed."
 
 # build and prepare the docs for release
-#
 release:
 	make mv-local
 	make deploy

docs/deploy.py

@@ -8,6 +8,7 @@ This is assumed to be executed from inside the docs/ folder.
 
 import glob
 import os
+import subprocess
 import sys
 
 # branches that should not be rebuilt anymore (all others are considered active)
@@ -18,7 +19,7 @@ latest_branch = "0.9.5"
 
 def deploy():
 
-    if os.popen("git status --untracked=no --porcelain"):
+    if subprocess.call(["git", "status", "--untracked=no", "--porcelain"]):
         print(
             "There are uncommitted or untracked changes. Make sure "
             "to commit everything in your current branch first."
@@ -26,35 +27,36 @@ def deploy():
         sys.exit(1)
 
     # get the deployment branch
-    os.popen("git fetch")
+    os.system("git fetch")
-    os.popen("git checkout gh-pages")
+    os.system("git checkout gh-pages")
 
     for file_path in glob.glob("*"):
         # run from inside the docs/ dir
         # delete old but active doc branches
 
-        _, filename = file_path.rsplit("/", 1).strip()
+        _, *filename = file_path.rsplit("/", 1)
 
-        if filename in legacy_branches:
+        if filename and filename[0] in legacy_branches:
             # skip deleting the legacy brancehs
             continue
         else:
             # we want to delete both active branches and old symlinks
-            os.popen(f"rm -Rf {file_path}")
+            print("remove file_path:", file_path)
+            os.system(f"rm -Rf {file_path}")
 
     # copy built branches to current dir
-    os.popen("cp -Rf build/html/* .")
+    os.system("cp -Rf build/html/* .")
     # symlink to latest and link its index to the root
-    os.popen(f"ln -s {latest_branch} latest")
+    os.system(f"ln -s {latest_branch} latest")
-    os.popen(f"ln -s {latest_branch}/index.html .")
+    os.system(f"ln -s {latest_branch}/index.html .")
 
     # docs/build is in .gitignore so will be skipped
-    os.popen("git add .")
+    os.system("git add .")
-    os.popen('git commit -a -m "Updated HTML docs."')
+    os.system('git commit -a -m "Updated HTML docs."')
-    os.popen("git push origin gh-pages")
+    os.system("git push origin gh-pages")
 
     # get back to previous branch
-    os.popen("git checkout .")
+    os.system("git checkout .")
 
     print("Deployed to https:// evennia.github.io/evennia/")
 

docs/deploy.sh

@@ -1,38 +0,0 @@
-# 
-# deploy to github 
-# 
-# This copies the recently built files from build/html into the github-gh branch. Note that 
-# it's important that build/ must not be committed to git!
-# 
-
-if [ -n "$(git status --untracked-files=no --porcelain)" ]; then
-  echo "There are uncommitted changes. Make sure to commit everything in your current branch first."
-  exit 1
-fi
-
-# get the deployment branch
-git fetch
-git checkout gh-pages
-# at this point we should be inside the docs/ folder of the gh-pages branch,
-# with the build/ directory available since this is not in git
-
-# remove all but the build dir
-# TODO don't delete old branches after 1.0 release; they will get harder and harder to rebuild
-ls -Q | grep -v build | xargs rm -Rf
-
-cp -Rf build/html/* .
-# TODO automate this? 
-ln -s 0.9.5 latest
-ln -s 0.9.5/index.html .
-
-# docs/build is in .gitignore so will not be included
-git add .
-
-git commit -a -m "Updated HTML docs"
-
-git push origin gh-pages
-
-# get back to previous branch 
-git checkout -
-
-echo "Deployed to https://evennia.github.io/evennia/"

docs/source/_templates/versioning.html

@@ -4,5 +4,11 @@
   {%- for item in versions %}
   <li><a href="{{ item.url }}">{{ item.release }} ({{ item.name }} branch)</a></li>
   {%- endfor %}
+</ul>
+    {% if legacy_versions %} <ul>
+      {%- for item in legacy_versions %}
+      <li><a href="{{ item.url }}">{{ item.release }} ({{ item.name }} branch)</a></li>
+      {%- endfor %}
     </ul>
     {% endif %}
+{% endif %}

docs/source/conf.py

@@ -7,6 +7,7 @@
 import os
 import re
 import sys
+from collections import namedtuple
 
 # from recommonmark.transform import AutoStructify
 from sphinx.util.osutil import cd
@@ -51,13 +52,23 @@ html_static_path = ["_static"]
 # -- Sphinx-multiversion config ----------------------------------------------
 
 # which branches to include in multi-versioned docs
-# - master, develop and vX.X branches
+# smv_branch_whitelist = r"^develop$|^v[0-9\.]+?$"
-smv_branch_whitelist = r"^develop$|^v[0-9\.]+?$"
+# smv_branch_whitelist = r"^develop$|^master$|^v1.0$"
+smv_branch_whitelist = r"^develop$"
 smv_outputdir_format = "{config.release}"
 # don't make docs for tags
 smv_tag_whitelist = r"^$"
-# legacy branches are linked to in template, but not built (custom for Evennia)
+
-smv_legacy_branches = ["0.9.5"]
+# used to fill in versioning.html links for versions that are not actually built
+legacy_versions = ["0.9.5"]
+
+
+def add_legacy_versions_to_html_page_context(app, pagename, templatename, context, doctree):
+    LVersion = namedtuple("legacy_version", ["release", "name", "url"])
+    context["legacy_versions"] = [
+        LVersion(release=f"{vers}", name=f"v{vers}", url=f"../{vers}/index.html")
+        for vers in legacy_versions
+    ]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -347,6 +358,7 @@ def setup(app):
     app.connect("autodoc-skip-member", autodoc_skip_member)
     app.connect("autodoc-process-docstring", autodoc_post_process_docstring)
     app.connect("source-read", url_resolver)
+    app.connect("html-page-context", add_legacy_versions_to_html_page_context)
 
     # build toctree file
     sys.path.insert(1, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))