diff --git a/README.md b/README.md index 5fde6230..66a11298 100644 --- a/README.md +++ b/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). diff --git a/docs/css/version-select.css b/docs/css/version-select.css new file mode 100644 index 00000000..49079bf4 --- /dev/null +++ b/docs/css/version-select.css @@ -0,0 +1,5 @@ +@media only screen and (max-width:76.1875em) { + #version-selector { + padding: .6rem .8rem; + } +} diff --git a/docs/js/version-select.js b/docs/js/version-select.js new file mode 100644 index 00000000..06a35bf9 --- /dev/null +++ b/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(); +}); diff --git a/mkdocs.yml b/mkdocs.yml index f36e94c6..5f18242b 100644 --- a/mkdocs.yml +++ b/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 diff --git a/requirements.txt b/requirements.txt index 3d45e820..0e881093 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,3 +8,4 @@ mkdocs>=1.0.4 mkdocs-material>=4.6.0 +mike>=0.5.1 \ No newline at end of file