fix links; add more links to ML tutorials/pytorch; add guides/tutorials section to landing page

bcumming · bcumming · commit 998eefd545d0 · 2025-08-22T15:09:36.000+02:00
diff --git a/docs/access/jupyterlab.md b/docs/access/jupyterlab.md
@@ -199,7 +199,7 @@ Examples of notebooks with `ipcmagic` can be found [here](https://github.com/
 
 While it is generally recommended to submit long-running machine learning training and inference jobs via `sbatch`, certain use cases can benefit from an interactive Jupyter environment.
 
-A popular approach to run multi-GPU ML workloads is with [`accelerate`](https://github.com/huggingface/accelerate) and [`torchrun`](https://docs.pytorch.org/docs/stable/elastic/run.html) as demonstrated in the [tutorials][ref-software-ml-tutorials].
+A popular approach to run multi-GPU ML workloads is with [`accelerate`](https://github.com/huggingface/accelerate) and [`torchrun`](https://docs.pytorch.org/docs/stable/elastic/run.html) as demonstrated in the [tutorials][ref-tutorials-ml].
 In particular, the `accelerate launch` script in the [LLM fine-tuning tutorial][software-ml-llm-fine-tuning-tutorial] can be directly carried over to a Jupyter cell with a `%%bash` header (to run its contents interpreted by bash).
 For `torchrun`, one can adapt the command from the multi-node [nanotron tutorial][software-ml-llm-nanotron-tutorial] to run on a single GH200 node using the following line in a Jupyter cell
 
diff --git a/docs/index.md b/docs/index.md
@@ -1,9 +1,3 @@
-!!! info ""
-    This is the new CSCS documentation site, which replaces the [CSCS Knowledge Base](https://confluence.cscs.ch/display/KB).
-
-    The migration of old documentation is still not fully complete.
-    If you find documentation that is missing, please create a ticket on the documentation's [GitHub issue tracker](https://github.com/eth-cscs/cscs-docs/issues).
-
 # CSCS Documentation
 
 <div class="grid cards" markdown>
@@ -66,32 +60,26 @@ The Alps Research infrastructure hosts multiple platforms and clusters targeting
 
 </div>
 
-[](){#ref-get-in-touch}
-## Get in Touch
+## Tutorials and Guides
 
-If you cannot find the information that you need in the documentation, help is available.
+Learn by doing with our guides and tutorials.
 
 <div class="grid cards" markdown>
+-   :fontawesome-solid-layer-group: __Tutorials__
 
--   :fontawesome-solid-headset: __Get Help__
-
-    Contact the CSCS Service Desk for help.
-
-    [:octicons-arrow-right-24: Service Desk](https://jira.cscs.ch/plugins/servlet/desk)
+    Hands on tutorials that show how to implement workflows on Alps.
 
--   :fontawesome-regular-comments: __Chat__
+    [:octicons-arrow-right-24: Machine Learning][ref-tutorials-ml]
 
-    Discuss Alps with other users and CSCS staff on Slack.
+-   :fontawesome-solid-mountain-sun: __Guides__
 
-    [:octicons-arrow-right-24: CSCS User Slack](https://cscs-users.slack.com/)
+    Guides with practical advice, hints and tips for key topics.
 
-<div class="grid cards" markdown>
--   :fontawesome-solid-hammer: __Contribute__
+    [:octicons-arrow-right-24: Using storage effectively][ref-guides-storage]
 
-    The source for the documentation is hosted on GitHub.
+    [:octicons-arrow-right-24: Accessing internet and external services][ref-guides-internet-access]
 
-    [:octicons-arrow-right-24: Contribute to the docs ](contributing/index.md)
-</div>
+    [:octicons-arrow-right-24: Using and configuring the terminal][ref-guides-terminal]
 
 </div>
 
@@ -142,3 +130,32 @@ If you cannot find the information that you need in the documentation, help is a
 
 </div>
 
+[](){#ref-get-in-touch}
+## Get in Touch
+
+If you cannot find the information that you need in the documentation, help is available.
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-headset: __Get Help__
+
+    Contact the CSCS Service Desk for help.
+
+    [:octicons-arrow-right-24: Service Desk](https://jira.cscs.ch/plugins/servlet/desk)
+
+-   :fontawesome-regular-comments: __Chat__
+
+    Discuss Alps with other users and CSCS staff on Slack.
+
+    [:octicons-arrow-right-24: CSCS User Slack](https://cscs-users.slack.com/)
+
+<div class="grid cards" markdown>
+-   :fontawesome-solid-hammer: __Contribute__
+
+    The source for the documentation is hosted on GitHub.
+
+    [:octicons-arrow-right-24: Contribute to the docs ](contributing/index.md)
+</div>
+
+</div>
+
diff --git a/docs/platforms/mlp/index.md b/docs/platforms/mlp/index.md
@@ -4,9 +4,11 @@
 The Machine Learning Platform (MLP) provides compute, storage and expertise to the machine learning and AI community in Switzerland, with the main user being the [Swiss AI Initiative](https://www.swiss-ai.org/).
 
 <div class="grid cards" markdown>
--   :fontawesome-solid-mountain: [__Tutorials__][ref-software-ml-tutorials]
+-   :fontawesome-solid-mountain: [__Tutorials__][ref-tutorials-ml]
 
-    Tutorials on how to set up and configure a machine learning environment in order to run LLM workloads such as inference, fine-tuning and multi-node training can be found in the [tutorials section][ref-software-ml-tutorials].
+    Tutorials on how to set up and configure a machine learning environment in order to run LLM workloads such as inference, fine-tuning and multi-node training can be found in the [tutorials section][ref-tutorials-ml].
+
+    Also check out the [PyTorch documentation][ref-software-ml-pytorch] for information about how to run PyTorch.
 
 </div>
 
diff --git a/docs/software/ml/index.md b/docs/software/ml/index.md
@@ -6,7 +6,7 @@ Most ML workloads are containerized to ensure portability, reproducibility, and
 
 Users can choose between running containers, using provided uenv software stacks, or building custom Python environments tailored to their needs.
 
-First time users are recommended to consult the [LLM tutorials][ref-software-ml-tutorials] to get familiar with the concepts of the Machine Learning platform in a series of hands-on examples. 
+First time users are recommended to consult the [LLM tutorials][ref-tutorials-ml] to get familiar with the concepts of the Machine Learning platform in a series of hands-on examples. 
 
 ## Running ML applications with containers (recommended)
 
@@ -28,7 +28,7 @@ Documented best practices are available for:
 
 Helpful references:
 
-* Introduction to concepts of the Machine Learning platform: [LLM tutorials][ref-software-ml-tutorials]
+* Introduction to concepts of the Machine Learning platform: [LLM tutorials][ref-tutorials-ml]
 * Running containers on Alps: [Container Engine Guide][ref-container-engine]
 * Building custom container images: [Container Build Guide][ref-build-containers]
 
diff --git a/docs/software/ml/pytorch.md b/docs/software/ml/pytorch.md
@@ -15,7 +15,8 @@ Running PyTorch from a container ensures maximum portability, reproducibility, a
 3. (optionally) extending with a virtual environment
 4. submitting jobs with CE in SLURM 
 
-These steps are illustrated in the [machine learning platform tutorials][ref-software-ml-tutorials] and the instructions detailed in the [podman build guide][ref-build-containers].
+!!! example
+    These steps are illustrated in the [machine learning tutorials][ref-tutorials-ml] and the instructions detailed in the [podman build guide][ref-build-containers].
 
 !!! info "Preliminary steps"
     Before proceeding with the next steps, make sure you have storage for podman configured as in the [build guide][ref-build-containers-configure-podman] and make sure to apply [recommended Lustre settings][ref-guides-storage-lustre] to every directory (e.g. `$SCRATCH/ce-images`) dedicated to container images before importing them with enroot. This is necessary to guarantee good filesystem performance.
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -1,2 +1,4 @@
 [](){#ref-tutorials}
 # Tutorials
+
+Currently there is one set of tutorials, for [machine learning workflows][ref-tutorials-ml].
diff --git a/docs/tutorials/ml/index.md b/docs/tutorials/ml/index.md
@@ -1,4 +1,4 @@
-[](){#ref-software-ml-tutorials}
+[](){#ref-tutorials-ml}
 # Machine Learning Platform Tutorials
 
 The LLM tutorials gradually introduce key concepts of the Machine Learning Platform in a series of hands-on examples. A particular focus is on the [Container Engine][ref-container-engine] for managing the runtime environment.
@@ -10,4 +10,4 @@ Building on the first tutorial, in the [second tutorial][software-ml-llm-fine-tu
 In the [third tutorial][software-ml-llm-nanotron-tutorial], you will apply the techniques from the previous tutorials to enable distributed (pre-)training of a model in `nanotron` on multiple nodes. In particular, this tutorial makes use of model-parallelism and introduces the usage of `torchrun` to manage jobs on individual nodes.
 
 !!! note
-    The focus for these tutorials is on introducing concepts of the Machine Learning Platform. As such, they do not necessarily discuss the latest advancements or steps required to obtain maximum performance. For this purpose, consult the framework-specific pages, such as the one for [PyTorch][ref-software-ml-pytorch]. 
+    The focus for these tutorials is on introducing concepts of the Machine Learning Platform. As such, they do not necessarily discuss the latest advancements or steps required to obtain maximum performance. For this purpose, consult the framework-specific pages, such as the one for [PyTorch][ref-software-ml-pytorch]. 
