enabling versioning of documentation:

README.md

@@ -6,11 +6,126 @@
 
 InvenioRDM user documentation web site.
 
-## Running
+## Run the docs locally
 
 ```console
 $ mkvirtualenv docs-invenio-rdm
 $ pip install -r requirements.txt
-$ mkdocs serve
+$ mkdocs serve # mike serve if you are using mike for versioning
 $ firefox http://127.0.0.1:8000
 ```
+
+## Set up versioning
+
+This means having `/x.y.z/` at the end of the url to point to a specific release
+version. You can also set up aliases to have `latest` or any desire string tag.
+
+### Initial setup, onte time operations
+
+#### Create the documentation branch
+
+Create and orphan branch called `gh-pages`. This name is mandatory to avoid
+extra configuration in mike and GitHub.
+
+``` console
+$ git checkout master
+$ git checkout --orphan gh-pages
+$ rm -rf ./*
+$ git rm -r ./*
+$ git commit -m "initial commit: index redirect"
+$ git push origin gh-pages
+```
+
+Why an orphan branch? In order to separate the build documentation from the
+source of it.
+
+#### Create a latest redirection
+
+By default GitHub pages serve the `index.html` file from the root directory.
+Mike does not build one by default, and we would like the documentation site
+to point to `/latest`. We can use the `set-default` command:
+
+``` console
+$ mike set-default latest -p
+```
+
+#### Install [mike](https://github.com/jimporter/mike)
+
+Create a new branch (to do a PR from) and install mike's extras:
+
+``` console
+$ git checkout master
+$ git checkout -b versioning
+$ mike install-extras
+```
+
+Add and commit the changes. This will include formating of the `mkdocs.yaml`
+plus some additions. As well as the css and js files needed for mike.
+
+``` console
+$ git add -p
+$ git add docs/css/
+$ git add docs/js/
+$ git commit -m "versioning: add mikes extras"
+$ git push origin versioning
+```
+
+**Note**: You might want to add `mike` to the requiresments.txt although it is
+not necesary for the build itself.
+
+### Operations
+
+#### Deploy!
+
+First of all fetch all branches to help mike sync. It does a great job on
+this, but is better to be sure.
+
+``` console
+$ git fetch --all
+```
+
+Then you need to build the new documentation. It is recommended to
+**not use** `-p` first. That way you can check the deployment (gh-pages
+branch) locally and then push upstream.
+
+``` console
+$ mike deploy 0.7.0 latest
+$ mike serve
+```
+
+Then deploy it (push it to gh-pages), if you want to update the aliases, for
+example to release a new latest. Use the `-u` option when deploying.
+
+``` console
+$ mike deploy 0.7.0 latest -p -u
+```
+
+**Warning**: after deploying you will get the `site/` folder. There is
+no need to commit it since it will be created each time you deploy.
+
+Finally, you should tag it and push it to github so it stays versioned.
+Note that you have pushed built documentation, but if you wish to be able
+to edit it in the future you need to save its source files.
+
+``` console
+$ git tag v0.7.0
+$ git push origin v0.7.0
+```
+
+#### Editing previous versions of the documentation
+
+As mentioned above, when deploying we do not store the source files. Those
+are stored in the git tags. Therefore, to edit previous documentation we
+should edit those.
+
+Then delete the old version of the docs and re-deploy:
+
+```console
+$ git checkout 0.6.3
+$ mike delete 0.6.3 -p
+$ # Perform edits, add and commit
+$ git tag 0.6.4 # Or delete the old tag to keep it consistent with the InvenioRDM versions
+$ mike deploy 0.6.3 -p
+```
+
+More docs [here](https://github.com/jimporter/mike).

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,50 @@
+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("/?assets/fonts/material-icons.css$");
+  var sheet = document.querySelector('link[href$="material-icons.css"]');
+
+  var REL_BASE_URL = sheet.getAttribute("href").replace(ex, "");
+  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", REL_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) {
+      return {text: i.title, value: i.version};
+    }), realVersion);
+    select.addEventListener("change", function(event) {
+      window.location.href = REL_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);
+  };
+  xhr.send();
+});

mkdocs.yml

@@ -1,75 +1,78 @@
 # Project information
-site_name: 'User Documentation'
-site_description: 'InvenioRDM user documentation web site'
-site_url: 'https://inveniordm.docs.cern.ch'
+site_name: User Documentation
+site_description: InvenioRDM user documentation web site
+site_url: https://inveniordm.docs.cern.ch
 
 # Repository
-repo_name: 'docs-invenio-rdm'
-repo_url: 'https://github.com/inveniosoftware/docs-invenio-rdm'
+repo_name: docs-invenio-rdm
+repo_url: https://github.com/inveniosoftware/docs-invenio-rdm
 
 # Copyright
-copyright: 'Copyright © 2019-2020 CERN and Northwestern University.'
+copyright: Copyright © 2019-2020 CERN and Northwestern University.
 
 # Configuration
 theme:
-  name: 'material'
-  custom_dir: 'theme'
-  palette:
-    primary: 'white'
-  font:
-    text: 'Open Sans'
-    code: 'Roboto Mono'
-  logo: 'images/logo-rdm.png'
-  favicon: 'images/favicon.svg'
-  feature:
-    tabs: true
+    name: material
+    custom_dir: theme
+    palette:
+        primary: white
+    font:
+        text: Open Sans
+        code: Roboto Mono
+    logo: images/logo-rdm.png
+    favicon: images/favicon.svg
+    feature:
+        tabs: true
 
 nav:
-  - Home: 'index.md'
+  - Home: index.md
   - Install:
-    - Installation: 'install/index.md'
+      - Installation: install/index.md
   - Preview:
-    - Quick preview of InvenioRDM: 'preview/index.md'
+      - Quick preview of InvenioRDM: preview/index.md
   - Develop:
-    - Getting Started: 'develop/index.md'
-    - Install Locally: 'develop/install_locally.md'
-    - Run: 'develop/run.md'
-    - Make it your own: 'develop/make_it_your_own.md'
-    - Troubleshooting: 'develop/troubleshoot.md'
-    - Cleanup: 'develop/cleanup.md'
+      - Getting Started: develop/index.md
+      - Install Locally: develop/install_locally.md
+      - Run: develop/run.md
+      - Make it your own: 'develop/make_it_your_own.md'
+      - Troubleshooting: develop/troubleshoot.md
+      - Cleanup: develop/cleanup.md
   - Extensions:
-    - What can be added?: 'extensions/index.md'
-    - Add your extensions: 'extensions/custom.md'
-    - S3 Storage: 'extensions/s3.md'
+      - What can be added?: extensions/index.md
+      - Add your extensions: extensions/custom.md
+      - S3 Storage: extensions/s3.md
   - Deploy:
-    - How can I deploy it?: 'deployment/index.md'
-    - OpenShift: 'deployment/openshift.md'
-    - Kubernetes: 'deployment/kubernetes.md'
-    - System components: 'deployment/services.md'
-    - Configuration:  'deployment/configuration.md'
-    - Building your image: 'deployment/image.md'
-    - Image registries: 'deployment/registries.md'
-    - Benchmarking: 'deployment/benchmark.md'
+      - How can I deploy it?: deployment/index.md
+      - OpenShift: deployment/openshift.md
+      - Kubernetes: deployment/kubernetes.md
+      - System components: deployment/services.md
+      - Configuration: deployment/configuration.md
+      - Building your image: deployment/image.md
+      - Image registries: deployment/registries.md
+      - Benchmarking: deployment/benchmark.md
 
 
 # Customization
 extra:
-  social:
-  - type: 'github'
-    link: 'https://github.com/inveniosoftware'
-  - type: 'twitter'
-    link: 'https://twitter.com/inveniosoftware'
-  - type: 'comments'
-    link: 'https://invenio-talk.web.cern.ch/c/projects/invenio-rdm'
-  - type: 'globe'
-    link: 'https://inveniosoftware.org/products/rdm/'
+    social:
+      - type: github
+        link: https://github.com/inveniosoftware
+      - type: twitter
+        link: https://twitter.com/inveniosoftware
+      - type: comments
+        link: https://invenio-talk.web.cern.ch/c/projects/invenio-rdm
+      - type: globe
+        link: https://inveniosoftware.org/products/rdm/
 extra_css:
   - stylesheets/extra.css
+  - css/version-select.css
 
 # Extensions
 markdown_extensions:
   - admonition
   - codehilite:
-      guess_lang: false
+        guess_lang: false
   - toc:
-      permalink: true
+        permalink: true
+extra_javascript:
+  - js/version-select.js

requirements.txt

@@ -8,3 +8,4 @@
 
 mkdocs>=1.0.4
 mkdocs-material>=4.6.0
+mike>=0.5.1