Add special URL docs

Author: juntyr

docs/compression.md

@@ -1,47 +1,8 @@
 # Online Laboratory for Data Compression in Climate Science and Meteorology
 
-Welcome to the **Online Laboratory for Data Compression in Climate Science and Meteorology**, [compression.lab.climet.eu](https://compression.lab.climet.eu)!
-
-If you are familiar with [JupyterLab](https://jupyter.org/), you should feel right at home with the user interface of this lab. You can use the JupyterLab interface at [/lab](https://lab.climet.eu/latest/lab) and a REPL interface at [/repl](https://lab.climet.eu/latest/repl).
-
-In fact, this laboratory is built using [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/), "a JupyterLab distribution that runs entirely in [your] browser" by leveraging WebAssembly. In other words, while you typically need to install JupyterLab on your own machine or connect to a server that executes your code, JupyterLite runs installation-free in your webbrowser and allows your code, data, and information to stay entirely on your machine. To run Python code within your browser, JupyterLite uses [Pyodide](https://pyodide.org/en/stable/), "a Python distribution for the browser [...] based on WebAssembly".
-
-While Pyodide already supports an extensive list of scientific Python packages, which we have contributed to, this laboratory comes with additional packages that are commonly used in the weather and climate science community, including (but not limited to) `metpy`, `cfgrib`, `earthkit`, and `xeofs`.
-
-
-## Getting Started
-
-To get started, click the blue `+` button in the top left to open a new launcher and create a new Python notebook from there. After the Python kernel has initialised, you can execute Python code in the cells of the notebook.
-
-!!! tip
-
-    While many Python packages can be `import`ed directly, additional pure Python packages can also be loaded by executing the `%pip install <PACKAGE>` magic inside a cell, after which the package can be imported.
-
-!!! note
-
-    The online laboratory has only been tested in recent Firefox and Chrome browsers. Some features may not (yet) be supported in Safari browsers.
-
-!!! attention
-
-    The online laboratory runs with the strict memory constraints of your web browser. It is therefore recommended to only open and execute one or two notebooks at a time. When a notebook is closed, the kernel will automatically shutdown to preserve resources.
-
-    If the online lab runs out of memory, you can save your work, close the notebook, and try to restart it. If you are still running low on memory, you should first download a copy of your notebooks, then reload the notebook page, re-upload the notebook, and continue working on them.
-
-    If you intend on executing memory intensive workloads, it is best to continue working on the notebooks locally instead. The online laboratory is primarily designed for initial exploration and for sharing codes in a reproducible environment.
-
-!!! caution
-
-    In the online laboratory, changes to notebooks and local files are only saved in your web browser's storage and not persisted to disk.
-
-    Please download copies of any files that you don't want to loose.
-
-    Your files from an old session will usually be kept if you close or refresh this page, unless your browser's storage for `lab.climet.eu` is cleared, e.g.
-
-    - manually by clearing the browser's site data
-    - automatically when too much data is stored
-    - automatically when you close a private browsing context
-    - if you have setup your browser to clear site data, e.g. when the browser is closed
+Welcome to the documentation for the **Online Laboratory for Data Compression in Climate Science and Meteorology**, [compression.lab.climet.eu](https://compression.lab.climet.eu)!
 
+Please first read about the [Online Laboratory for Climate Science and Meteorology][online-laboratory-for-climate-science-and-meteorology] to get familiar with the environment that the Online Laboratory for Data Compression is hosted in.
 
 ## Overview of the provided notebooks
 
@@ -51,7 +12,7 @@ The **Online Laboratory for Data Compression** comes with several Jupyter notebo
 2. showcase different compression methods on various weather and climate datasets
 3. allow you to easily and quickly test out compression on *your* data
 
-The following is an overview of all notebooks:
+The following is an overview of all notebooks (clicking a link opens the specified file in the online compression laboratory):
 
 - [`01-intro.ipynb`](https://compression.lab.climet.eu/v0.2/01-intro.ipynb): First introduction to the online laboratory, data loading, compression, and visualisation
 - [`02-data-sources/`](https://compression.lab.climet.eu/v0.2/02-data-sources/README.md): Small examples on how to open datasets from different sources

docs/lab.md docs/lab/index.mddocs/lab.md renamed to docs/lab/index.md

@@ -1,17 +1,15 @@
 # Online Laboratory for Climate Science and Meteorology
 
-Welcome to the **Online Laboratory for Climate Science and Meteorology**, [lab.climet.eu](https://lab.climet.eu)!
+Welcome to the documentation for the **Online Laboratory for Climate Science and Meteorology**, [lab.climet.eu](https://lab.climet.eu)!
 
-If you are familiar with [JupyterLab](https://jupyter.org/), you should feel right at home with the user interface of this lab. You can use the JupyterLab interface at [/lab](https://lab.climet.eu/latest/lab) and a REPL interface at [/repl](https://lab.climet.eu/latest/repl).
-
-In fact, this laboratory is built using [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/), "a JupyterLab distribution that runs entirely in [your] browser" by leveraging WebAssembly. In other words, while you typically need to install JupyterLab on your own machine or connect to a server that executes your code, JupyterLite runs installation-free in your webbrowser and allows your code, data, and information to stay entirely on your machine. To run Python code within your browser, JupyterLite uses [Pyodide](https://pyodide.org/en/stable/), "a Python distribution for the browser [...] based on WebAssembly".
+If you are familiar with [JupyterLab](https://jupyter.org/), you should feel right at home with the user interface of this lab. In fact, this laboratory is built using [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/), "a JupyterLab distribution that runs entirely in [your] browser" by leveraging WebAssembly. In other words, while you typically need to install JupyterLab on your own machine or connect to a server that executes your code, JupyterLite runs installation-free in your webbrowser and allows your code, data, and information to stay entirely on your machine. To run Python code within your browser, JupyterLite uses [Pyodide](https://pyodide.org/en/stable/), "a Python distribution for the browser [...] based on WebAssembly".
 
 While Pyodide already supports an extensive list of scientific Python packages, which we have contributed to, this laboratory comes with additional packages that are commonly used in the weather and climate science community, including (but not limited to) `metpy`, `cfgrib`, `earthkit`, and `xeofs`.
 
 
 ## Getting Started
 
-To get started, click the blue `+` button in the top left to open a new launcher and create a new Python notebook from there. After the Python kernel has initialised, you can execute Python code in the cells of the notebook.
+To get started, go to [lab.climet.eu](https://lab.climet.eu), wait for the JupyterLab to load, and click the blue `+` button in the top left to open a new launcher and create a new Python notebook from there. After the Python kernel has initialised, you can execute Python code in the cells of the notebook.
 
 !!! tip
 

docs/lab/urls.md

@@ -0,0 +1,28 @@
+The Online Laboratory for Climate Science and Meteorology, [lab.climet.eu](https://lab.climet.eu), supports the following special URL patterns for downloading git repositories into the lab during startup:
+
+- `https://lab.climet.eu/`: opens the latest version of the lab
+- `https://lab.climet.eu/<version>`: opens the specified version of the lab
+- `https://lab.climet.eu/<version>/[github|gitlab]/<org>/<repo>/<branch>`: downloads the specified GitHub / GitLab repository in the specified version of the lab
+- `https://lab.climet.eu/<version>/[github|gitlab]/<org>/<repo>/<branch>/*filepath`: downloads the specified GitHub / GitLab repository in the specified version of the lab and opens the file path
+- `https://lab.climet.eu/<version>gist/[github]/<org>/<gist>/*filepath`: downloads the specified GitHub gist file and opens it in the specified version of the lab
+- `https://lab.climet.eu/<version>/raw/[github]/<org>/<repo>/<branch>/*filepath`: downloads the specified file from a GitHub repository's branch and opens it in the specified version of the lab
+- `https://lab.climet.eu/<version>/raw/[github-tag]/<org>/<repo>/<tag>/*filepath`: downloads the specified file from a GitHub repository's tag and opens it in the specified version of the lab
+
+where
+
+- `<version>` refers to one of the following published versions of the lab:
+    - `latest`: the latest published version, currently `v0.2.1`
+    - `v0.2`: the latest version of the 0.2.x release stream, currently `v0.2.1`
+    - `v0.2.1`
+    - `v0.2.0`
+    - `v0.1`: the latest version of the 0.1.x release stream, currently `v0.1.0`
+    - `v0.1.0`
+
+    The online lab follows semantic versioning, i.e. breaking changes to the lab and the packages it provides are only made in breaking releases. To ensure that your code works in the laboratory as expected, you should use one of the *.x release streams, e.g. `v0.1` or `v0.2`.
+
+- `<org>` refers to the organisation / user that owns a GitHub / GitLab repository
+- `<repo>` refers to the name of the repository
+- `<branch>` refers to the name of a branch in the repository
+- `<tag>` refers to the name of a tag in the repository
+- `<gist>` refers to the hash of a GitHub gist
+- `*filepath` refers to an optional path, starting from the repository root, for a file that should be opened

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: climet.eu Documentation
+site_name: climet.eu Docs
 site_url: https://docs.climet.eu
 repo_url: https://github.com/climet-eu
 
@@ -43,7 +43,9 @@ theme:
 
 nav:
   - Home: index.md
-  - Online Laboratory: lab.md
+  - Online Laboratory:
+    - Overview: lab/index.md
+    - Special URLs: lab/urls.md
   - Online Compression Laboratory: compression.md
 
 plugins: