From d3e62de99e6b08ac00f255279b7f5587b0dbb825 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 14 Nov 2022 21:30:05 +0100 Subject: [PATCH] Testing alternative versioning --- docs/Makefile | 3 -- docs/deploy.py | 28 ++++++++++--------- docs/deploy.sh | 38 -------------------------- docs/source/_templates/versioning.html | 6 ++++ docs/source/conf.py | 20 +++++++++++--- 5 files changed, 37 insertions(+), 58 deletions(-) delete mode 100644 docs/deploy.sh diff --git a/docs/Makefile b/docs/Makefile index 972ec07219..1341f308fc 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/deploy.py b/docs/deploy.py index 22277ecd60..1ae830af12 100644 --- a/docs/deploy.py +++ b/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.popen("git checkout gh-pages") + os.system("git fetch") + 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.popen(f"ln -s {latest_branch}/index.html .") + os.system(f"ln -s {latest_branch} latest") + os.system(f"ln -s {latest_branch}/index.html .") # docs/build is in .gitignore so will be skipped - os.popen("git add .") - os.popen('git commit -a -m "Updated HTML docs."') - os.popen("git push origin gh-pages") + os.system("git add .") + os.system('git commit -a -m "Updated HTML docs."') + 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/") diff --git a/docs/deploy.sh b/docs/deploy.sh deleted file mode 100644 index e35af73b94..0000000000 --- a/docs/deploy.sh +++ /dev/null @@ -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/" diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html index 02eaef1396..7e366252fd 100644 --- a/docs/source/_templates/versioning.html +++ b/docs/source/_templates/versioning.html @@ -5,4 +5,10 @@
  • {{ item.release }} ({{ item.name }} branch)
    • {%- endfor %} + {% if legacy_versions %} + {% endif %} {% endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py index a5f3c206c9..271c9fae5b 100644 --- a/docs/source/conf.py +++ b/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__))))