generate dynamic links

docs/conf.py

@@ -1,3 +1,5 @@
+import semver
+
 # Configuration file for the Sphinx documentation builder.
 #
 # This file only contains a selection of the most common options. For a full
@@ -95,3 +97,62 @@
 # External TOC options
 external_toc_path = "_toc.yml"
 external_toc_exclude_missing = True
+
+# __get_download_url returns the download URL for the given file, for the latest or the given GitHub release.
+def __get_download_url(file: str) -> str:
+    if not 'current_version' in html_context or not __is_sem_version(html_context['current_version']):
+        return f"https://github.com/liqotech/liqo/releases/latest/download/{file}"
+    else:
+        return f"https://github.com/liqotech/liqo/releases/download/{html_context['current_version']}/{file}"
+
+# generate_clone_example generates the clone and checkout code for the given example.
+def generate_clone_example(example_name: str) -> str:
+    return f"```bash\n\
+git clone https://github.com/liqotech/liqo.git\n\
+cd liqo\n\
+git checkout {html_context['github_version']}\n\
+cd examples/{example_name}\n\
+./setup.sh\n\
+```\n"
+
+# generate_liqoctl_install generates the liqoctl installation instruction for the given platform and architecture.
+def generate_liqoctl_install(platform: str, arch: str) -> str:
+    if platform == 'windows':
+        return f"```bash\n\
+curl --fail -LSO \"{__get_download_url('liqoctl-windows-amd64')}\"\n\
+```\n"
+    elif platform == 'darwin':
+        file = __get_download_url(f"liqoctl-darwin-{arch}")
+        return f"```bash\n\
+curl --fail -LS --output liqoctl \"{file}\"\n\
+chmod +x liqoctl\n\
+sudo mv liqoctl /usr/local/bin/liqoctl\n\
+```\n"
+    elif platform == 'linux':
+        file = __get_download_url(f"liqoctl-linux-{arch}")
+        return f"```bash\n\
+curl --fail -LS --output liqoctl \"{file}\"\n\
+sudo install -o root -g root -m 0755 liqoctl /usr/local/bin/liqoctl\n\
+```\n"
+
+# __is_sem_version returns True if the given string is a semantic version or the 'stable' string.
+def __is_sem_version(version: str) -> bool:
+    return version == 'stable' or semver.VersionInfo.isvalid(version)
+
+# generate_liqoctl_version_warning generates the liqoctl version warning when the documentation is not for a released version.
+def generate_liqoctl_version_warning() -> str:
+    if not 'github_version' in html_context or not __is_sem_version(html_context['github_version']):
+        return "```{warning}\n\
+The following instructions will guide you through the installation of the **latest stable version of *liqoctl***, which might exhibit a different behavior compared to the one shown in the rest of this documentation. If you want to use the latest *liqoctl* version, [build it from source](InstallationLiqoctlFromSource).\n\
+```\n"
+    return ""
+
+html_context = {
+    'generate_clone_example': generate_clone_example,
+    'generate_liqoctl_install': generate_liqoctl_install,
+    'generate_liqoctl_version_warning': generate_liqoctl_version_warning,
+    'github_repo': 'liqo',
+    'github_version': 'master',
+    'display_github': True,
+    'commit': 'abcdefgh',
+}

docs/examples/global-ingress.md

@@ -15,11 +15,7 @@ Specifically, this tool is leveraged instead of KinD to match the [K8GB Sample D
 
 To provision the playground, clone the [Liqo repository](https://github.com/liqotech/liqo) and run the setup script:
 
-```bash
-git clone https://github.com/liqotech/liqo.git
-cd liqo/examples/global-ingress
-./setup.sh
-```
+{{ env.config.html_context.generate_clone_example('global-ingress') }}
 
 The setup script creates three k3s clusters and deploys the appropriate infrastructural application on top of them, as detailed in the following:
 

docs/examples/offloading-with-policies.md

@@ -13,11 +13,7 @@ First, check that you are compliant with the [requirements](/examples/requiremen
 Then, let's open a terminal on your machine and launch the following script, which creates the three above-mentioned clusters with KinD and installs Liqo on all of them.
 Each cluster is made by a single combined control-plane + worker node.
 
-```bash
-git clone https://github.com/liqotech/liqo.git
-cd liqo/examples/offloading-with-policies
-./setup.sh
-```
+{{ env.config.html_context.generate_clone_example('offloading-with-policies') }}
 
 Export the kubeconfigs environment variables to use them in the rest of the tutorial:
 

docs/examples/quick-start.md

@@ -10,11 +10,7 @@ First, check that you are compliant with the [requirements](/examples/requiremen
 Then, let's open a terminal on your machine and launch the following script, which creates a pair of clusters with KinD.
 Each cluster is made by two nodes (one for the control plane and one as a simple worker):
 
-```bash
-git clone https://github.com/liqotech/liqo.git
-cd liqo/examples/quick-start
-./setup.sh
-```
+{{ env.config.html_context.generate_clone_example('quick-start') }}
 
 ### Explore the playground
 

docs/examples/service-offloading.md

@@ -11,11 +11,7 @@ First, check that you are compliant with the [requirements](/examples/requiremen
 Then, let's open a terminal on your machine and launch the following script, which creates the two above-mentioned clusters with KinD and installs Liqo on them.
 Each cluster is made by a single combined control-plane + worker node.
 
-```bash
-git clone https://github.com/liqotech/liqo.git
-cd liqo/examples/service-offloading
-./setup.sh
-```
+{{ env.config.html_context.generate_clone_example('service-offloading') }}
 
 Export the kubeconfigs environment variables to use them in the rest of the tutorial:
 

docs/examples/stateful-applications.md

@@ -10,11 +10,7 @@ First, check that you are compliant with the [requirements](/examples/requiremen
 Then, let's open a terminal on your machine and launch the following script, which creates the two above-mentioned clusters with KinD and installs Liqo on them.
 Each cluster is made by a single combined control-plane + worker node.
 
-```bash
-git clone https://github.com/liqotech/liqo.git
-cd liqo/examples/stateful-applications
-./setup.sh
-```
+{{ env.config.html_context.generate_clone_example('stateful-applications') }}
 
 Export the kubeconfigs environment variables to use them in the rest of the tutorial:
 

docs/installation/liqoctl.md

@@ -14,6 +14,8 @@ Specifically, it abstracts the creation and modification of Liqo defined custom
 *liqoctl* displays a *kubectl* compatible behavior concerning Kubernetes API access, hence supporting the `KUBECONFIG` environment variable, as well as the standard flags, including `--kubeconfig` and `--context`.
 ```
 
+{{ env.config.html_context.generate_liqoctl_version_warning() }}
+
 ## Install liqoctl with Homebrew
 
 If you are using the [Homebrew](https://brew.sh/) package manager, you can install *liqoctl* with Homebrew:
@@ -31,21 +33,15 @@ You can download and install *liqoctl* manually, following the appropriate instr
 `````{tab-set}
 ````{tab-item} Linux
 
-Download *liqoctl* and move it a to a file location in your system `PATH`:
+Download *liqoctl* and move it to a file location in your system `PATH`:
 
 **AMD64:**
 
-```bash
-curl --fail -LS --output liqoctl "https://get.liqo.io/liqoctl-linux-amd64"
-sudo install -o root -g root -m 0755 liqoctl /usr/local/bin/liqoctl
-```
+{{ env.config.html_context.generate_liqoctl_install('linux', 'amd64') }}
 
 **ARM64:**
 
-```bash
-curl --fail -LS --output liqoctl "https://get.liqo.io/liqoctl-linux-arm64"
-sudo install -o root -g root -m 0755 liqoctl /usr/local/bin/liqoctl
-```
+{{ env.config.html_context.generate_liqoctl_install('linux', 'arm64') }}
 
 ```{admonition} Note
 Make sure `/usr/local/bin` is in your `PATH` environment variable.
@@ -54,23 +50,15 @@ Make sure `/usr/local/bin` is in your `PATH` environment variable.
 
 ````{tab-item} MacOS
 
-Download *liqoctl*, make it executable, and move it a to a file location in your system `PATH`:
+Download *liqoctl*, make it executable, and move it to a file location in your system `PATH`:
 
 **Intel:**
 
-```bash
-curl --fail -LS --output liqoctl "https://get.liqo.io/liqoctl-darwin-amd64"
-chmod +x liqoctl
-sudo mv liqoctl /usr/local/bin/liqoctl
-```
+{{ env.config.html_context.generate_liqoctl_install('darwin', 'amd64') }}
 
 **Apple Silicon:**
 
-```bash
-curl --fail -LS --output liqoctl "https://get.liqo.io/liqoctl-darwin-arm64"
-chmod +x liqoctl
-sudo mv liqoctl /usr/local/bin/liqoctl
-```
+{{ env.config.html_context.generate_liqoctl_install('darwin', 'arm64') }}
 
 ```{admonition} Note
 Make sure `/usr/local/bin` is in your `PATH` environment variable.
@@ -81,18 +69,30 @@ Make sure `/usr/local/bin` is in your `PATH` environment variable.
 
 Download the *liqoctl* binary:
 
-```bash
-curl --fail -LSO "https://get.liqo.io/liqoctl-windows-amd64"
-```
+{{ env.config.html_context.generate_liqoctl_install('windows', 'amd64') }}
 
 And move it to a file location in your system `PATH`.
 
 ````
 `````
 
-Alternatively, you can download *liqoctl* from the [Liqo releases](https://github.com/liqotech/liqo/releases/) page on GitHub.
+Alternatively, you can manually download *liqoctl* from the [Liqo releases](https://github.com/liqotech/liqo/releases/) page on GitHub.
+
+(InstallationLiqoctlFromSource)=
+
+## Install liqoctl from source
+
+You can install *liqoctl* building it from source.
+To do so, clone the Liqo repository, build the *liqoctl* binary, and move it to a file location in your system `PATH`:
+
+```bash
+git clone https://github.com/liqotech/liqo.git
+cd liqo
+make ctl
+mv liqoctl /usr/local/bin/liqoctl
+```
 
-### Enable shell autocompletion
+## Enable shell autocompletion
 
 *liqoctl* provides autocompletion support for Bash, Zsh, Fish, and PowerShell.
 

docs/requirements.txt

@@ -4,3 +4,4 @@ sphinx_rtd_theme==1.0.0
 sphinx-copybutton==0.5.0
 sphinx-design==0.2.0
 sphinx_external_toc==0.3.0
+semver==2.13.0