Added multiple versions to the documentation.

hategan · hategan · commit babca12745df · 2023-03-22T21:10:49.000-07:00
There are multiple parts to this:
- sphinx-multiversion is used to build docs from all release tags when
doing a web build; resulting docs are in `/docs/v/&lt;version&gt;`.
- `/docs/index.html` now has some JS to figure out the latest version and
redirect to it
- a version selector is added to the sidebar
- there is some JS to collapse all `x.y.z(*)` into `x.y.z` and map `x.y.z`
to the latest `x.y.z(*)` (e.g., `0.1.0` -&gt; `0.1.0post2`; basically we
use the latest post release available and hide the others with the same
version.
diff --git a/Makefile b/Makefile
@@ -56,7 +56,8 @@ docs:
 .PHONY: web-docs
 web-docs:
 	rm -rf docs/.generated
-	sphinx-build -W -b html -D html_theme='cloud' -D templates_path='_templates' docs docs/.web-build/
+	rm -rf docs/.web-build
+	PSIJ_WEB_DOCS=1 sphinx-multiversion docs docs/.web-build
 
 .PHONY: style
 style:
diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html
@@ -0,0 +1,4 @@
+{% if versions %}
+    {% include "../../web/_includes/versionselect.html" %}
+{% endif %}
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -8,16 +8,22 @@
 import sphinx_rtd_theme
 from sphinx.ext.apidoc import main
 
+web_docs = False
+if 'PSIJ_WEB_DOCS' in os.environ:
+	web_docs = True
+
 needs_sphinx = '1.6'
 
 # Set Sphinx variables
 master_doc = 'index'
 
 project = u'PSI/J'
 copyright = u'The ExaWorks Team'
-
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+if web_docs:
+	html_theme = 'cloud'
+else:
+	html_theme = 'sphinx_rtd_theme'
+	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_favicon = 'favicon.ico'
 autoclass_content = 'both'
 add_module_names = False
@@ -28,7 +34,18 @@
     ('py:class', 'distutils.version.Version')
 ]
 
+if web_docs:
+	templates_path = ['_templates']
+	# Multi-version
+	smv_branch_whitelist = '^mathcmeifyoucan$'
+	smv_remote_whitelist = None
+	smv_released_pattern = r'^\d+\.\d+\.\d+(\..*)?$'
+	smv_outputdir_format = 'v/{ref.name}'
+
+
 html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}
+if web_docs:
+	html_sidebars['**'].insert(0, 'versioning.html')
 
 # These are needed for the dhtml trickery
 html_static_path = ["_static"]
@@ -44,6 +61,9 @@
     'sphinx.ext.viewcode',
 ]
 
+if web_docs:
+    extensions.append('sphinx_multiversion')
+
 autodoc_typehints = "description"
 autodoc_typehints_format = "short"
 
@@ -69,10 +89,8 @@
 # Copied from https://github.com/readthedocs/readthedocs.org/issues/1139
 
 # run api doc
-def run_apidoc(_):
-    output_path = os.path.join(script_dir, '.generated')
-    print(f"OUTPUT PATH = {output_path}")
-    #exclusions = [os.path.join(src_dir, 'setup.py'),]
+def run_apidoc(sphinx):
+    output_path = os.path.join(sphinx.srcdir, '.generated')
     main(['-f', '-o', output_path, src_dir])
 
 # launch setup
diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -10,6 +10,7 @@ six
 Sphinx==4.5.0
 sphinx_rtd_theme
 sphinx-tabs
+sphinx-multiversion
 
 # For the web version of the docs
 cloud_sptheme == 1.10.1.post20200504175005
diff --git a/web/_includes/head.html b/web/_includes/head.html
@@ -16,3 +16,5 @@
     <link rel="stylesheet"
         href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.4.0/styles/base16/tender.min.css">
     <script src="https://kit.fontawesome.com/0f2ef02e2b.js" crossorigin="anonymous"></script>
+    <script src="{{ site.baseurl }}/versions.js"></script>
+    <script src="{{ site.baseurl }}/versioning.js"></script>
diff --git a/web/_includes/versionselect.html b/web/_includes/versionselect.html
@@ -0,0 +1,3 @@
+            <div id="version-selector">
+                <v-select prefix="Version" :items="getSortedVersionLabels()" @change="setVersion" v-model="version"></v-select>
+            </div>
diff --git a/web/_includes/vueinit.html b/web/_includes/vueinit.html
@@ -4,7 +4,12 @@
             el: '#psij-app',
             vuetify: new Vuetify(),
             data: {
-                maintabs: {{ page.tab }}
+                maintabs: {{ page.tab }},
+                version: getCurrentVersion()
+            },
+            methods: {
+                getSortedVersionLabels: getSortedVersionLabels,
+                setVersion: setVersion
             }
         });
 
diff --git a/web/build.sh b/web/build.sh
@@ -18,8 +18,26 @@ if [ "$1" != "--quick" ]; then
 	cp -r docs/.web-build/. web-build/docs/
 fi
 
-cp -r web/. web-build/
-cp web/*.css web-build/docs/
+
+cp -r web/_layouts/ web-build/
+cp -r web/_includes/ web-build/
+
+echo -n "var DOC_VERSIONS_RAW = [" >web-build/versions.js
+for V in `ls web-build/docs/v`; do
+	echo "Patching version $V"
+	cp -r web/docs/_static web-build/docs/v/$V/
+
+	echo "\"$V\", " >>web-build/versions.js
+done
+echo "]" >>web-build/versions.js
+
+for F in `ls web/*`; do
+	if [ -f "$F" ]; then
+		cp "$F" web-build/
+	fi
+done
+
+cp web/docs/index.html web-build/docs/
 
 rm -f web-build/*.sh
-rm -f web-build/README
+rm -f web-build/README
diff --git a/web/docs/_static/cloud.css b/web/docs/_static/cloud.css
@@ -40,6 +40,7 @@ ul, ol {
 
 div.relbar-top {
     background-color: #e0e0e0;
+    border-bottom: 1px solid var(--color-fg-lines);
 }
 
 
@@ -112,7 +113,7 @@ div.body {
 }
 
 div.sphinxsidebar {
-    margin-top: 32pt;
+    margin-top: 4pt;
     width: 3in;
     font-size: 90%;
     line-height: 1.25em;
@@ -123,7 +124,7 @@ div.document.sidebar-hidden div.sphinxsidebar {
 }
 
 div.sphinxsidebarwrapper {
-    padding: 1em 0 0 10px;
+    padding: 0 0 0 10px;
 }
 
 div.sphinxsidebar h3, div.sphinxsidebar h4 {
diff --git a/web/docs/index.html b/web/docs/index.html
@@ -0,0 +1,29 @@
+---
+title: PSI/J - Python
+layout: raw
+tab: 2
+---
+
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Documentation - PSI/J - Python</title>
+        <script src="{{ site.baseurl }}/versions.js"></script>
+        <script src="{{ site.baseurl }}/versioning.js"></script>
+    </head>
+    <body>
+        <script type="application/javascript">
+            var latest = getLatestVersion();
+            document.write("Redirecting to <a href=\"v/" + latest + "\">Version " + latest + " documentation</a>");
+            var loc = window.location.href;
+            if (loc.endsWith(".html")) {
+                loc = loc.substring(0, loc.lastIndexOf("/"));
+            }
+            if (loc.endsWith("/")) {
+                loc = loc.substring(0, loc.length - 1);
+            }
+            window.location = loc + "/v/" + latest + "/";
+        </script>
+    </body>
+</html>
+
diff --git a/web/style.css b/web/style.css
@@ -230,3 +230,76 @@ pre {
     width: 100%;
     font-weight: 900 !important;
 }
+
+
+/*** Versioning ***/
+
+#version-selector {
+    margin-top: 4pt;
+    margin-right: 4pt;
+}
+
+#version-selector .v-text-field__prefix {
+    height: 20px;
+    margin-left: 4pt;
+}
+
+#version-selector .v-text-field__prefix, #version-selector .v-select__selections {
+    font-size: 10pt;
+}
+
+#version-selector .v-input {
+    margin: 0;
+    padding: 0;
+}
+
+#version-selector .v-select__selections {
+    line-height: 14pt;
+}
+
+#version-selector .v-select__selection--comma {
+    margin: 1pt 1pt 1pt 0;
+}
+
+#version-selector input {
+    max-width: 0px;
+    border: none;
+}
+
+#version-selector .v-text-field>.v-input__control>.v-input__slot:before {
+    border-color: transparent;
+}
+
+#version-selector .v-input__append-inner {
+    border-top: 0;
+}
+
+#version-selector .v-input__slot {
+    transition: 0.3s cubic-bezier(0.25, 0.8, 0.5, 1);
+}
+
+#version-selector .v-input__slot:hover {
+    background-color: rgba(0, 0, 0, 0.12);
+}
+
+.v-menu__content .v-list-item__content {
+    padding: 4pt 0;
+}
+
+.v-menu__content .v-list-item {
+    max-height: 24pt;
+    min-height: 10pt;
+}
+
+.v-menu__content .v-list-item__title {
+    font-size: 10pt;
+    color: var(--color-fg-norm-1);
+}
+
+#psij-app .v-menu__content .v-list-item--active {
+    background-color: rgba(red(var(--color-fg-lines)), green(var(--color-fg-lines)), blue(var(--color-fg-lines)), 0.12);
+}
+
+#psij-app .v-menu__content .v-list-item:hover {
+    background-color: rgba(0, 0, 0, 0.12);
+}
diff --git a/web/versioning.js b/web/versioning.js
@@ -0,0 +1,119 @@
+
+var DOC_VERSIONS = {};
+var DOC_SORTED_VERSIONS = [];
+var DOC_LATEST_VERSION = null;
+
+function versionSplit(v) {
+    var nparts = v.split(".", 3);
+    
+    if (nparts.length != 3) {
+        throw new Error("Invalid version: " + v);
+    }
+    
+    var last = nparts[2];
+    var ix = last.search(/[^0-9]/);
+    var suffix = "";
+    if (ix >= 0) {
+        nparts[2] = last.substring(0, ix);
+        suffix = last.substring(ix);
+    }
+    
+    var version = nparts[0] + "." + nparts[1] + "." + nparts[2];
+    
+    for (var i = 0; i < 3; i++) {
+        nparts[i] = parseInt(nparts[i]);
+    }
+    
+    return {version: version, nparts: nparts, suffix: suffix, raw: v};
+}
+
+function compareVN(v1, v2) {
+    for (var i = 0; i < 3; i++) {
+        var d = v1.nparts[i] - v2.nparts[i];
+        if (d != 0) {
+            return -d;
+        }
+    }
+    return 0;
+}
+
+function compareV(v1, v2) {
+    var nd = compareVN(v1, v2);
+    if (nd != 0) {
+        return nd;
+    }
+    else {
+        return v1.suffix.localeCompare(v2.suffix);
+    }
+}
+
+function compareSV(sv1, sv2) {
+    return compareV(versionSplit(sv1), versionSplit(sv2));
+}
+
+function initVersions() {
+    /* We need to sort them, coalesce 0.1.0* to 0.1.0 and make sure 0.1.0 
+    points to the latest in the set of 0.1.0'es. We also set DOC_LATEST_VERSION.
+    The order is numeric for the numeric parts and lexicographic for the 
+    trailing part. */
+    var vs = {};
+    
+    for (var i = 0; i < DOC_VERSIONS_RAW.length; i++) {
+        var v = versionSplit(DOC_VERSIONS_RAW[i]);
+        console.log(v);
+        if (!(v.version in vs)) {
+            vs[v.version] = {all: []};
+        }
+        console.log(vs);
+        vs[v.version].all.push(v);
+    }
+    
+    for (var key in vs) {
+        vs[key].all.sort((v1, v2) => {return v1.suffix.localeCompare(v2.suffix);});
+        vs[key].latest = vs[key].all[0];
+        DOC_SORTED_VERSIONS.push(vs[key].latest);
+    }
+    
+    DOC_SORTED_VERSIONS.sort(compareVN);
+    DOC_LATEST_VERSION = DOC_SORTED_VERSIONS[0].version;
+    DOC_VERSIONS = vs;
+}
+
+function getLatestVersion() {
+    return DOC_LATEST_VERSION;
+}
+
+function getSortedVersionLabels() {
+    return DOC_SORTED_VERSIONS.map(v => v.version);
+}
+
+function splitLocation() {
+    var url = window.location.href;
+    
+    var ix1 = url.indexOf("/docs/v/");
+    if (ix1 >= 0) {
+        var rest = url.substring(ix1 + "/docs/v/".length);
+        var ix2 = rest.indexOf("/");
+        if (ix2 >= 0) {
+            return [url.substring(0, ix1) + "/docs/v", rest.substring(0, ix2), rest.substring(ix2 + 1)];
+        }
+        else {
+            return [url.substring(0, ix1) + "/docs/v", rest, ""];
+        }
+    }
+    else {
+        return [url, "unknown", ""];
+    }
+}
+
+function setVersion() {    
+    var s = splitLocation();
+    
+    window.location = s[0] + "/" + this.version + "/" + s[2];
+}
+
+function getCurrentVersion() {
+    return splitLocation()[1];
+}
+
+initVersions();

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+ <div id="version-selector">`
	`2`	`+ <v-select prefix="Version" :items="getSortedVersionLabels()" @change="setVersion" v-model="version"></v-select>`
	`3`	`+ </div>`
Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ ul, ol {`
`40`	`40`
`41`	`41`	`div.relbar-top {`
`42`	`42`	`background-color: #e0e0e0;`
	`43`	`+ border-bottom: 1px solid var(--color-fg-lines);`
`43`	`44`	`}`
`44`	`45`
`45`	`46`
`@@ -112,7 +113,7 @@ div.body {`
`112`	`113`	`}`
`113`	`114`
`114`	`115`	`div.sphinxsidebar {`
`115`		`- margin-top: 32pt;`
	`116`	`+ margin-top: 4pt;`
`116`	`117`	`width: 3in;`
`117`	`118`	`font-size: 90%;`
`118`	`119`	`line-height: 1.25em;`
`@@ -123,7 +124,7 @@ div.document.sidebar-hidden div.sphinxsidebar {`
`123`	`124`	`}`
`124`	`125`
`125`	`126`	`div.sphinxsidebarwrapper {`
`126`		`- padding: 1em 0 0 10px;`
	`127`	`+ padding: 0 0 0 10px;`
`127`	`128`	`}`
`128`	`129`
`129`	`130`	`div.sphinxsidebar h3, div.sphinxsidebar h4 {`