Documentation version selector (#204)

Dockerfile

@@ -5,8 +5,9 @@ RUN apt-get update && \
     rm -rf /var/lib/apt/lists/*
 
 RUN pip3 install twine \
-                 mkdocs \
-                 mkdocs-material \
+                 mkdocs==1.1.2 \
+                 mkdocs-material==6.2.2 \
+                 mike==0.5.5 \
                  git+https://github.com/moritzmeister/keras-autodoc@split-tags-properties
 
 RUN mkdir -p /.local && chmod -R 777 /.local

Jenkinsfile_doc

@@ -7,27 +7,33 @@ pipeline {
             agent {
                 docker {
                     label "local"
-                    image "docker.hops.works/hopsworks_twine:0.0.3"
+                    image "docker.hops.works/hopsworks_twine:0.0.4"
                 }
             }
-
+            environment {
+              TOKEN = credentials('token')
+            }
             steps {
+                dir("java") {
+                    sh "mvn org.apache.maven.plugins:maven-help-plugin:2.1.1:evaluate -Dexpression=project.version | grep -Ev '(^\\[|Download\\w+:)' > ../version.log"
+                }
                 dir("python") {
                     sh "pip3 install -e .[dev,docs]"
                 }
                 sh "python3 auto_doc.py"
-                sh "mkdocs build"
-            }
-        }
-
-        stage("publish") {
-            agent {
-                node "local"
-            }
-
-            steps {
-                sh "rm -r /opt/docs/*"
-                sh "cp -r site/* /opt/docs/"
+                sh '''
+                  git config user.name jenkins
+                  git config user.email jenkins@hops.works
+                  export VERSION=\$(cat version.log) &&
+                  if [[ "$VERSION" == *SNAPSHOT ]]
+                  then
+                    export TAG="dev --update-aliases"
+                  else
+                    export TAG=
+                  fi
+                  echo "$token"
+                  mike deploy \$VERSION \$TAG --push -r https://hopsworksjenkins:$token@github.com/logicalclocks/feature-store-api
+                '''
             }
         }
     }

docs/css/version-select.css

@@ -0,0 +1,5 @@
+@media only screen and (max-width:76.1875em) {
+  #version-selector {
+    padding: .6rem .8rem;
+  }
+}

docs/js/version-select.js

@@ -0,0 +1,54 @@
+window.addEventListener("DOMContentLoaded", function() {
+  // This is a bit hacky. Figure out the base URL from a known CSS file the
+  // template refers to...
+  var ex = new RegExp("/?css/version-select.css$");
+  var sheet = document.querySelector('link[href$="version-select.css"]');
+
+  var ABS_BASE_URL = sheet.href.replace(ex, "");
+  var CURRENT_VERSION = ABS_BASE_URL.split("/").pop();
+
+  function makeSelect(options, selected) {
+    var select = document.createElement("select");
+    select.classList.add("form-control");
+
+    options.forEach(function(i) {
+      var option = new Option(i.text, i.value, undefined,
+                              i.value === selected);
+      select.add(option);
+    });
+
+    return select;
+  }
+
+  var xhr = new XMLHttpRequest();
+  xhr.open("GET", ABS_BASE_URL + "/../versions.json");
+  xhr.onload = function() {
+    var versions = JSON.parse(this.responseText);
+
+    var realVersion = versions.find(function(i) {
+      return i.version === CURRENT_VERSION ||
+             i.aliases.includes(CURRENT_VERSION);
+    }).version;
+
+    var select = makeSelect(versions.map(function(i) {
+      if (i.aliases.length > 0) {
+        var aliasString = " [" + i.aliases.join(", ") + "]";
+      } else {
+        var aliasString = "";
+      }
+      return {text: i.title + aliasString, value: i.version};
+    }), realVersion);
+    select.addEventListener("change", function(event) {
+      window.location.href = ABS_BASE_URL + "/../" + this.value;
+    });
+
+    var container = document.createElement("div");
+    container.id = "version-selector";
+    // container.className = "md-nav__item";
+    container.appendChild(select);
+
+    var sidebar = document.querySelector(".md-nav--primary > .md-nav__list");
+    sidebar.parentNode.insertBefore(container, sidebar.nextSibling);
+  };
+  xhr.send();
+});

mkdocs.yml

@@ -94,6 +94,10 @@ extra:
 
 extra_css:
     - css/custom.css
+    - css/version-select.css
+
+extra_javascript:
+    - js/version-select.js
 
 plugins:
     - search

python/setup.py

@@ -31,8 +31,9 @@ def read(fname):
             "flake8",
             "black"],
         "docs": [
-            "mkdocs",
-            "mkdocs-material",
+            "mkdocs==1.1.2",
+            "mkdocs-material==6.2.2",
+            "mike==0.5.5",
             "keras-autodoc",
             "markdown-include"],
         "hive": ["pyhopshive[thrift]", "sqlalchemy", "PyMySQL"],