refactoring for round 2

Author: bcumming

docs/software-deployment/index.md

@@ -1,7 +1,37 @@
-# Software Deployment
+# Alps environments
 
-!!! todo
-    section on uenv and container engine
+Once you have logged into a [cluster][ref-alps-clusters] on Alps, you will want to set up your environment and find the software and tools provided by CSCS.
+This part of the documentation will give guidance on how to set up your shell, and how to access software in uenv and container environments.
 
-!!! todo
-    section on building your own software
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-layer-group: __Set up your login environment__
+
+    A good spot to start is to read our guide on configuring your shell.
+
+    [:octicons-arrow-right-24: Using the terminal][ref-platform-hpcp]
+
+</div>
+
+<div class="grid cards" markdown>
+
+-   :fontawesome-solid-layer-group: __Setting up your development and simulation environments__
+
+    CSCS provides two ways to acess software, and create the environment used to develop and run.
+
+    Scientitic HPC workloads are a good fit for uenv -- a tool developed by CSCS to deliver scientific software stacks on Alps.
+
+    [:octicons-arrow-right-24: uenv][ref-uenv]
+
+    The container engine runtime is recommended for machine learning workflows.
+    It can also be a very good choice for Python environments installed using pip, uv and conda.
+
+    [:octicons-arrow-right-24: container engine][ref-container-engine]
+
+</div>
+
+
+!!! todo "links to programming environments"
+    Provide links to programming environements, software and Frameworks (which are in a different top level section).
+
+    This helps with discoverability.

mkdocs.yml

@@ -31,36 +31,16 @@ nav:
     - 'Climate and Weather Platform':
       - platforms/cwp/index.md
       - 'Santis': clusters/santis.md
-  - 'Accounts and Projects':
-    - accounts/index.md
-    - 'Account and Resources Management Tool': accounts/ump.md
-    - 'Project and Resources Management Tool': accounts/waldur.md
-    - 'Creating a new account': accounts/account-create.md
   - 'Connecting to Alps':
     - access/index.md
     - 'Multi Factor Authentication (MFA)': access/mfa.md
     - 'Web Services': access/web.md
     - 'SSH': access/ssh.md
     - 'JupyterLab': access/jupyterlab.md
     - 'VSCode': access/vscode.md
-  - 'Running Jobs':
-    - running/index.md
-    - 'Slurm': running/slurm.md
-    - 'Job report': running/jobreport.md
-    - 'Known issues': running/known-issues.md
-  - 'Machine Learning':
-    - ml/index.md
-    - 'PyTorch': software/ml/pytorch.md
-    - 'Tutorials':
-      - ml/tutorials/index.md
-      - 'LLM Inference': ml/tutorials/llm-inference.md
-      - 'LLM Fine-tuning': ml/tutorials/llm-fine-tuning.md
-      - 'LLM Pre-training': ml/tutorials/llm-nanotron-training.md
-    - 'Data management': ml/data.md
-    - 'Tuning and optimization': ml/tuning.md
-    - 'Inference Workflows': ml/inference.md
-  - 'Software Deployment':
+  - 'Environments':
     - software-deployment/index.md
+    - 'Using the terminal': guides/terminal.md
     - 'uenv':
       - software/uenv/index.md
       - 'Configuration': software/uenv/configure.md
@@ -73,31 +53,20 @@ nav:
       - 'Resource and hooks': software/container-engine/resource-hook.md
       - 'EDF reference': software/container-engine/edf.md
       - 'Known issues': software/container-engine/known-issue.md
-    - 'Building software':
-      - build-install/index.md
-      - 'uenv': build-install/uenv.md
-      - 'Containers (podman)': build-install/containers.md
-    - 'Community codes':
-      - build-install/applications/index.md
-      - 'Matlab': build-install/applications/matlab.md
-      - 'WRF': build-install/applications/wrf.md
-  - 'Software':
-    - software/index.md
-    - 'Scientific Applications':
-      - software/sciapps/index.md
-      - 'CP2K': software/sciapps/cp2k.md
-      - 'GROMACS': software/sciapps/gromacs.md
-      - 'LAMMPS': software/sciapps/lammps.md
-      - 'NAMD': software/sciapps/namd.md
-      - 'Quantum ESPRESSO': software/sciapps/quantumespresso.md
-      - 'VASP': software/sciapps/vasp.md
+  - 'Building and Installing Software':
+    - build-install/index.md
     - 'Programming Environments':
       - software/prgenv/index.md
       - 'prgenv-gnu': software/prgenv/prgenv-gnu.md
       - 'prgenv-nvfortran': software/prgenv/prgenv-nvfortran.md
       - 'linalg': software/prgenv/linalg.md
       - 'julia': software/prgenv/julia.md
       - 'Cray modules (CPE)': software/prgenv/cpe.md
+    - 'How to build software':
+      - 'uenv': build-install/uenv.md
+    - 'Packaging and Deployment':
+      - 'Creating uenv': software/uenv/build.md
+      - 'Creating Containers with podman': build-install/containers.md
     - 'Communication Libraries':
       - software/communication/index.md
       - 'Cray MPICH': software/communication/cray-mpich.md
@@ -106,18 +75,48 @@ nav:
       - 'NCCL': software/communication/nccl.md
       - 'RCCL': software/communication/rccl.md
       - 'libfabric': software/communication/libfabric.md
-    - 'Debugging and Performance Analysis':
-      - software/devtools/index.md
-      - 'Using NVIDIA Nsight': software/devtools/nvidia-nsight.md
-      - 'Using Linaro Forge':
-        - software/devtools/linaro-uenv.md
-        - 'Linaro performance analysis tool': software/devtools/linaro-map.md
-        - 'Linaro debugger': software/devtools/linaro-ddt.md
-      - 'Using Score-P/Scalasca': software/devtools/vihps.md
+  - 'Software and Frameworks':
+    - software/index.md
+    - 'Scientific Applications':
+      - software/sciapps/index.md
+      - 'CP2K': software/sciapps/cp2k.md
+      - 'GROMACS': software/sciapps/gromacs.md
+      - 'LAMMPS': software/sciapps/lammps.md
+      - 'NAMD': software/sciapps/namd.md
+      - 'Quantum ESPRESSO': software/sciapps/quantumespresso.md
+      - 'VASP': software/sciapps/vasp.md
+    - 'Machine Learning':
+      - ml/index.md
+      - 'PyTorch': software/ml/pytorch.md
+      - 'Tutorials':
+        - ml/tutorials/index.md
+        - 'LLM Inference': ml/tutorials/llm-inference.md
+        - 'LLM Fine-tuning': ml/tutorials/llm-fine-tuning.md
+        - 'LLM Pre-training': ml/tutorials/llm-nanotron-training.md
+      - 'Data management': ml/data.md
+    - 'Tuning and optimization': ml/tuning.md
+    - 'Inference Workflows': ml/inference.md
+    - 'Community codes':
+      - build-install/applications/index.md
+      - 'Matlab': build-install/applications/matlab.md
+      - 'WRF': build-install/applications/wrf.md
     - 'Scientific Visualization':
       - software/sciviz/index.md
       - 'ParaView': software/sciviz/paraview.md
     - 'Unsupported Software': software/unsupported.md
+  - 'Debugging and Performance Analysis':
+    - software/devtools/index.md
+    - 'Using NVIDIA Nsight': software/devtools/nvidia-nsight.md
+    - 'Using Linaro Forge':
+      - software/devtools/linaro-uenv.md
+      - 'Linaro performance analysis tool': software/devtools/linaro-map.md
+      - 'Linaro debugger': software/devtools/linaro-ddt.md
+    - 'Using Score-P/Scalasca': software/devtools/vihps.md
+  - 'Running Jobs':
+    - running/index.md
+    - 'Slurm': running/slurm.md
+    - 'Job report': running/jobreport.md
+    - 'Known issues': running/known-issues.md
   - 'Services':
     - services/index.md
     - 'FirecREST': services/firecrest.md
@@ -133,11 +132,15 @@ nav:
     - 'Data Transfer': storage/transfer.md
     - 'Long Term Storage': storage/longterm.md
     - 'Object Storage': storage/object.md
+  - 'Accounts and Projects':
+    - accounts/index.md
+    - 'Account and Resources Management Tool': accounts/ump.md
+    - 'Project and Resources Management Tool': accounts/waldur.md
+    - 'Creating a new account': accounts/account-create.md
   - 'Guides':
     - guides/index.md
     - 'Internet Access on Alps': guides/internet-access.md
     - 'Storage': guides/storage.md
-    - 'Using the terminal': guides/terminal.md
     - 'Gordon Bell 2025': guides/gb25.md
   - 'Policies':
     - policies/index.md