From 6c12d54f5c6d4c08f2b0e2a2b57546b1b1fd3895 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Thu, 3 Apr 2025 09:52:43 +0200 Subject: [PATCH 1/4] Update code blocks to be a bit more consistent - Use console instead of terminal - Use bash when there's no output --- docs/access/mfa.md | 4 +- docs/clusters/clariden.md | 4 +- docs/clusters/santis.md | 4 +- docs/contributing/index.md | 16 ++-- docs/guides/gb2025.md | 4 +- docs/guides/terminal.md | 2 +- docs/software/container-engine.md | 12 +-- docs/software/devtools/linaro-ddt.md | 10 +-- docs/software/devtools/linaro-forge.md | 14 +-- docs/software/prgenv/prgenv-gnu.md | 20 ++--- docs/software/prgenv/prgenv-nvfortran.md | 6 +- docs/software/uenv.md | 110 +++++++++++------------ docs/storage/object.md | 6 +- readme.md | 6 +- 14 files changed, 109 insertions(+), 109 deletions(-) diff --git a/docs/access/mfa.md b/docs/access/mfa.md index c5f01905..900c1dae 100644 --- a/docs/access/mfa.md +++ b/docs/access/mfa.md @@ -50,8 +50,8 @@ Before starting, ensure that the following pre-requisites are satisfied !!! warning If you try to SSH to CSCS systems without setting up MFA, you will be prompted with permission denied error, for example: - ``` - > ssh ela.cscs.ch + ```console + $ ssh ela.cscs.ch bobsmith@ela.cscs.ch: Permission denied (publickey). Connection closed by UNKNOWN port 65535 ``` diff --git a/docs/clusters/clariden.md b/docs/clusters/clariden.md index dbbe636b..1b16773f 100644 --- a/docs/clusters/clariden.md +++ b/docs/clusters/clariden.md @@ -84,8 +84,8 @@ See the SLURM documentation for instructions on how to run jobs on the [Grace-Ho ??? example "how to check the number of nodes on the system" You can check the size of the system by running the following command in the terminal: - ```terminal - > sinfo --format "| %20R | %10D | %10s | %10l | %10A |" + ```console + $ sinfo --format "| %20R | %10D | %10s | %10l | %10A |" | PARTITION | NODES | JOB_SIZE | TIMELIMIT | NODES(A/I) | | debug | 32 | 1-2 | 30:00 | 3/29 | | normal | 1266 | 1-infinite | 1-00:00:00 | 812/371 | diff --git a/docs/clusters/santis.md b/docs/clusters/santis.md index 58630875..a3564e1f 100644 --- a/docs/clusters/santis.md +++ b/docs/clusters/santis.md @@ -98,8 +98,8 @@ See the SLURM documentation for instructions on how to run jobs on the [Grace-Ho ??? example "how to check the number of nodes on the system" You can check the size of the system by running the following command in the terminal: - ```terminal - > sinfo --format "| %20R | %10D | %10s | %10l | %10A |" + ```console + $ sinfo --format "| %20R | %10D | %10s | %10l | %10A |" | PARTITION | NODES | JOB_SIZE | TIMELIMIT | NODES(A/I) | | debug | 32 | 1-2 | 30:00 | 3/29 | | normal | 1266 | 1-infinite | 1-00:00:00 | 812/371 | diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 1592c9df..e0a5a461 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -13,20 +13,20 @@ We use the GitHub fork and pull request model for development: Clone your fork repository on your PC/laptop: ```bash # clone your fork of the repository -> git clone git@github.com:${githubusername}/cscs-docs.git -> cd cscs-docs -> git switch -c 'fix/ssh-alias' +git clone git@github.com:${githubusername}/cscs-docs.git +cd cscs-docs +git switch -c 'fix/ssh-alias' # ... make your edits ... # add and commit your changes -> git add -> git commit -m 'update the ssh docs with aliases for all user lab vclusters' -> git push origin 'fix/ssh-alias' +git add +git commit -m 'update the ssh docs with aliases for all user lab vclusters' +git push origin 'fix/ssh-alias' ``` Then navigate to GitHub, and create a pull request. The `serve` script in the root path of the repository can be used to view the docs locally:` -``` -> ./serve +```bash +./serve ... INFO - [08:33:34] Serving on http://127.0.0.1:8000/ ``` diff --git a/docs/guides/gb2025.md b/docs/guides/gb2025.md index daf0de46..7ae29120 100644 --- a/docs/guides/gb2025.md +++ b/docs/guides/gb2025.md @@ -45,9 +45,9 @@ The consequence of this setting is that only 71 cores per socket can be requeste !!! warning "Unable to allocate resources: Requested node configuration is not availabl" If you try to use all 72 cores on each socket, SLURM will give a hard error, because only 71 are available: - ``` + ```console # try to run 4 ranks per node, with 72 cores each - > srun -n4 -N1 -c72 --reservation=reshuffling ./build/affinity.mpi + $ srun -n4 -N1 -c72 --reservation=reshuffling ./build/affinity.mpi srun: error: Unable to allocate resources: Requested node configuration is not available ``` diff --git a/docs/guides/terminal.md b/docs/guides/terminal.md index fa939c30..a9f98fd5 100644 --- a/docs/guides/terminal.md +++ b/docs/guides/terminal.md @@ -14,7 +14,7 @@ At CSCS the vast majority of users stick with the default `bash`: at the time of Run the following command after logging in: - ```terminal + ```console $ getent passwd | grep $USER bcumming:*:22008:1000:Benjamin Cumming, CSCS:/users/bcumming:/usr/local/bin/bash ``` diff --git a/docs/software/container-engine.md b/docs/software/container-engine.md index 6231d38f..72fd1d81 100644 --- a/docs/software/container-engine.md +++ b/docs/software/container-engine.md @@ -50,13 +50,13 @@ Since the `ubuntu.toml` file is located in the [EDF search path][ref-ce-edf-sear The above terminal snippet demonstrates how to launch a containerized environment using Slurm with the `--environment` option. Click on the :fontawesome-solid-circle-plus: icon for information on each command. - ```bash - daint-ln002 > srun --environment=ubuntu --pty bash # (1) + ```console + [daint-ln002]$ srun --environment=ubuntu --pty bash # (1) - nid005333 > pwd # (2) + [nid005333]$ pwd # (2) /capstor/scratch/cscs/ - nid005333 > cat /etc/os-release # (3) + [nid005333]$ cat /etc/os-release # (3) PRETTY_NAME="Ubuntu 24.04 LTS" NAME="Ubuntu" VERSION_ID="24.04" @@ -71,8 +71,8 @@ Since the `ubuntu.toml` file is located in the [EDF search path][ref-ce-edf-sear UBUNTU_CODENAME=noble LOGO=ubuntu-logo - nid005333 > exit # (4) - daint-ln002 > + [nid005333]$ exit # (4) + [daint-ln002]$ ``` 1. Starting an interactive shell session within the Ubuntu 24.04 container deployed on a compute node using `srun --environment=ubuntu --pty bash`. diff --git a/docs/software/devtools/linaro-ddt.md b/docs/software/devtools/linaro-ddt.md index ae9d6e68..ca292627 100644 --- a/docs/software/devtools/linaro-ddt.md +++ b/docs/software/devtools/linaro-ddt.md @@ -18,7 +18,7 @@ The following guide will walk through the steps required to build and debug an a Once the uenv is loaded and activated, the program to debug must be compiled with the `-g` (for CPU) and `-G` (for GPU) debugging flags. For example, we can build a CUDA test with a user environment: -```terminal +```bash uenv start prgenv-gnu:24.11:v1 --view=default nvcc -c -arch=sm_90 -g -G test_gpu.cu mpicxx -g test_cpu.cpp test_gpu.o -o myexe @@ -41,13 +41,13 @@ To use the DDT client with uenv, it must be launched in `Manual Launch` mode Log into the system and launch with the `srun` command: - ```terminal + ```console # start a session with both the PE used to build your application # and the linaro-forge uenv mounted - > uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default - > source /user-tools/activate + $ uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default + $ source /user-tools/activate - > srun -N1 -n4 -t15 -pdebug ./cuda_visible_devices.sh ddt-client ./myexe + $ srun -N1 -n4 -t15 -pdebug ./cuda_visible_devices.sh ddt-client ./myexe ``` ### Start debugging diff --git a/docs/software/devtools/linaro-forge.md b/docs/software/devtools/linaro-forge.md index 5085d1a7..5d162c8d 100644 --- a/docs/software/devtools/linaro-forge.md +++ b/docs/software/devtools/linaro-forge.md @@ -18,12 +18,12 @@ The Linaro uenv is named `linaro-forge`, and the available versions can be deter !!! example "finding available linaro-forge versions" - ``` - > uenv image find linaro-forge + ```console + $ uenv image find linaro-forge uenv arch system id size(MB) date linaro-forge/24.1.1:v1 gh200 daint e0e79f5c3e6a8ee0 365 2025-02-12 - > uenv image pull linaro-forge/24.1.1:v1 + $ uenv image pull linaro-forge/24.1.1:v1 pulling e0e79f5c3e6a8ee0 100.00% --- 365/365 (0.00 MB/s) ``` @@ -50,10 +50,10 @@ Version: 24.1.1 !!! note The `linaro-forge` uenv is always mounted at the `/user-tools` mount point, and a script `/user-tools/activate` is provided to load both ddt and map into your environment, without needing to use a view. - ```bash - > uenv start linaro-forge/14.1.1 - > source /user-tools/activate - > ddt --version + ```console + $ uenv start linaro-forge/14.1.1 + $ source /user-tools/activate + $ ddt --version Linaro DDT Part of Linaro Forge. Copyright (c) 2023-2024 Linaro Limited. All rights reserved. Version: 24.1.1 diff --git a/docs/software/prgenv/prgenv-gnu.md b/docs/software/prgenv/prgenv-gnu.md index 023fd042..272fdd5d 100644 --- a/docs/software/prgenv/prgenv-gnu.md +++ b/docs/software/prgenv/prgenv-gnu.md @@ -81,22 +81,22 @@ There are three ways to access the software provided by prgenv-gnu, once it has The simplest way to get started is to use the `default` file system view, which automatically loads all of the packages when the uenv is started. !!! example "test mpi compilers and python provided by prgenv-gnu/24.11" - ```bash + ```console # start using the default view - > uenv start --view=default prgenv-gnu/24.11:v1 + $ uenv start --view=default prgenv-gnu/24.11:v1 # the python executable provided by the uenv is the default, and is a recent version - > which python + $ which python /user-environment/env/default/bin/python - > python --version + $ python --version Python 3.12.5 # the mpi compiler wrappers are also available - > which mpicc + $ which mpicc /user-environment/env/default/bin/mpicc - > mpicc --version + $ mpicc --version gcc (Spack GCC) 13.3.0 - > gcc --version # the compiler wrapper uses the gcc provided by the uenv + $ gcc --version # the compiler wrapper uses the gcc provided by the uenv gcc (Spack GCC) 13.3.0 ``` @@ -106,9 +106,9 @@ There are three ways to access the software provided by prgenv-gnu, once it has No modules are loaded when a uenv starts, and have to be loaded individually using `module load`. !!! example "starting prgenv-gnu and listing the provided modules" - ```bash - > uenv start prgenv-gnu/24.11:v1 --view=modules - > module avail + ```console + $ uenv start prgenv-gnu/24.11:v1 --view=modules + $ module avail ---------------------------- /user-environment/modules ---------------------------- aws-ofi-nccl/git.v1.9.2-aws_1.9.2 lua/5.4.6 boost/1.86.0 lz4/1.10.0 diff --git a/docs/software/prgenv/prgenv-nvfortran.md b/docs/software/prgenv/prgenv-nvfortran.md index c09d151d..929a27f5 100644 --- a/docs/software/prgenv/prgenv-nvfortran.md +++ b/docs/software/prgenv/prgenv-nvfortran.md @@ -92,9 +92,9 @@ uenv image find prgenv-nvfortran/24.11:v1 The modules view will start the uenv, and make a set of modules available: - ``` - > uenv start prgenv-nvfortran/24.11:v1 --view=nvfort,modules - > module avail + ```console + $ uenv start prgenv-nvfortran/24.11:v1 --view=nvfort,modules + $ module avail ---------------------------- /user-environment/modules ---------------------------- aws-ofi-nccl/master libtree/3.1.1 ninja/1.12.1 cmake/3.30.5 lua/5.4.6 nvhpc/24.11 diff --git a/docs/software/uenv.md b/docs/software/uenv.md index 31b017fd..8b1c4949 100644 --- a/docs/software/uenv.md +++ b/docs/software/uenv.md @@ -19,10 +19,10 @@ Each environment contains a software stack, comprised of compilers, libraries, t After logging into an Alps cluster, you can quickly check the availability of uenv with the following commands: -```terminal -> uenv status +```console +$ uenv status there is no uenv loaded -> uenv --version +$ uenv --version 7.0.0 ``` @@ -126,8 +126,8 @@ Uenv for programming environments, tools and applications are provided by CSCS o The available uenv images are stored in a registry, that can be queried using the `uenv image find` command: !!! example "uenv image find" - ``` terminal - > uenv image find + ```console + $ uenv image find uenv arch system id size(MB) date cp2k/2024.1:v1 zen2 eiger 2a56f1df31a4c196 2,693 2024-07-01 cp2k/2024.2:v1 zen2 eiger f83e95328d654c0f 2,739 2024-08-23 @@ -157,22 +157,22 @@ The output above shows that there are 12 uenv (`prgenv-gnu`, `namd` , `cp2k` and To create a repo in the default location, use the following command: - ```terminal title="Create default uenv image repository" - > uenv repo create + ```bash title="Create default uenv image repository" + uenv repo create ``` To use a uenv, it first has to be pulled from the registry to local storage where you can access it. For example, to use the `prgenv-gnu` uenv, use the uenv image pull command: !!! example "uenv image pull" - ```terminal + ```bash # The following commands have the same effect # method 1: pull using the name of the uenv - > uenv image pull prgenv-gnu/24.2:v1 + uenv image pull prgenv-gnu/24.2:v1 # method 2: pull using the id of the image - > uenv image pull 3ea1945046d884ee + uenv image pull 3ea1945046d884ee ``` Some images can be large, over 10 GB, and it can take a while to download them from the registry. @@ -180,8 +180,8 @@ Some images can be large, over 10 GB, and it can take a while to download them f To view all uenv that have been pulled, and are ready to use use the `uenv image ls` command: !!! example "listing downloaded uenv" - ```terminal - > uenv image ls + ```console + $ uenv image ls uenv arch system id size(MB) date editors/24.7:v2 gh200 daint e7b0d930df729da5 1,270 2024-09-04 gromacs/2024:v1 gh200 daint b58e6406810279d5 3,658 2024-09-12 @@ -205,7 +205,7 @@ To be able to pull such images a token that authorizes access must be provided. Tokens are created by CSCS, and stored on SCRATCH in a file that only users who have access to the software can read. !!! example "using a token to access VASP" - ```terminal + ```bash uenv image pull \ --token=/capstor/scratch/cscs/bcumming/tokens/vasp6 \ --username=vasp6 \ @@ -227,25 +227,25 @@ This is very useful for interactive sessions, for example if you want to work in !!! example "start an interactive shell to compile an application" Here we want to compile an MPI + CUDA application "affinity". - ```terminal + ```console # start the prgenv-gnu uenv, which provides MPI, cuda and CMake # use the "default" view, which will load all of the software in the uenv - > uenv start prgenv-gnu/24.11:v1 --view=default + $ uenv start prgenv-gnu/24.11:v1 --view=default # clone the software and set up the build directory - > git clone https://github.com/bcumming/affinity.git - > mkdir -p affinity/build - > cd affinity/build/ + $ git clone https://github.com/bcumming/affinity.git + $ mkdir -p affinity/build + $ cd affinity/build/ # configure the build with CMake, then call make to build # mpicc, mpic++ and cmake are all provided by the uenv - > CXX=mpic++ CC=mpicc cmake .. - > make -j + $ CXX=mpic++ CC=mpicc cmake .. + $ make -j # run the affinity executable on two nodes - note how the uenv is # automatically loaded by slurm on the compute nodes, because CUDA and MPI from # the uenv are required to run. - > srun -n2 -N2 ./affinity.cuda + $ srun -n2 -N2 ./affinity.cuda GPU affinity test for 2 MPI ranks rank 0 @ nid005636 cores : 0-287 @@ -261,7 +261,7 @@ This is very useful for interactive sessions, for example if you want to work in gpu 3 : GPU-e07d996e-4d67-c9f4-cf75-81cfd45a1ae1 # finish the uenv session - > exit + $ exit ``` @@ -270,7 +270,7 @@ This is very useful for interactive sessions, for example if you want to work in `uenv start` starts a new shell, and by default it will use the default shell for the user. You can see the default shell by looking at the `$SHELL` environment variable. If you want to force a different shell: - ``` + ```bash SHELL=`which zsh` uenv start ... ``` @@ -283,15 +283,15 @@ The basic syntax of uenv start is `uenv start image` where `image` is the uenv t The image can be a label, the hash/id of the uenv, or a file: !!! example "uenv start" - ``` + ```console # start the image using the name of the uenv - > uenv start netcdf-tools/2024:v1 + $ uenv start netcdf-tools/2024:v1 # or use the unqique id of the uenv - > uenv start 499c886f2947538e + $ uenv start 499c886f2947538e # or provide the path to a squashfs file - > uenv start $SCRATCH/my-uenv/gromacs.squashfs + $ uenv start $SCRATCH/my-uenv/gromacs.squashfs ``` @@ -300,29 +300,29 @@ The image can be a label, the hash/id of the uenv, or a file: The squashfs image of a uenv is a directory that contains all of the software provided by the uenv, along with useful meta data. When you run `uenv start` (or `uenv run`, or use the `--uenv` flag with SLURM) the squashfs file is mounted at the mount location for the uenv, which is most often `/user-environment`. - ``` + ```console # log into daint - > ssh daint.alps.cscs.ch + $ ssh daint.alps.cscs.ch # /user-environment is empty - > ls -l /user-environment + $ ls -l /user-environment total 0 # start a uenv - > uenv start prgenv-nvfortran/24.11:v1 + $ uenv start prgenv-nvfortran/24.11:v1 # the uenv software is now available - > ls /user-environment/ + $ ls /user-environment/ bin config env linux-sles15-neoverse_v2 meta modules repo # findmnt verifies that a squashfs image has been mounted - > findmnt /user-environment + $ findmnt /user-environment TARGET SOURCE FSTYPE OPTIONS /user-environment /dev/loop25 squashfs ro,nosuid,nodev,relatime,errors=continue # end the session and verify that the uenv is not longer mounted - > exit - > ls -l /user-environment + $ exit + $ ls -l /user-environment total 0 ``` @@ -337,16 +337,16 @@ Uenv images provide **views**, which will set environment variables that load th Views are loaded using the `--view` flag for `uenv start` (also for `uenv run` and the SLURM plugin, documented below) !!! example "loading views" - ```terminal + ```console # activate the view named default in prgenv-gnu - > uenv start --view=default prgenv-gnu/24.11:v1 + $ uenv start --view=default prgenv-gnu/24.11:v1 # activate both the spack and modules views in prgenv-gnu using # a comma-separated list of view names - > uenv start --view=spack,modules prgenv-gnu/24.11:v1 + $ uenv start --view=spack,modules prgenv-gnu/24.11:v1 # when starting multiple uenv, you can disambiguate using uenvname:viewname - > uenv start --view=prgenv-gnu:default,editors:ed prgenv-gnu/24.11:v1,editors + $ uenv start --view=prgenv-gnu:default,editors:ed prgenv-gnu/24.11:v1,editors ``` #### Modules @@ -355,9 +355,9 @@ Most uenv provide the modules, that can be accessed using the `module` command. By default, the modules are not activated when a uenv is started, and need to be explicitly activated using the `module` view. !!! example "using the module view" - ```terminal - > uenv start prgenv-gnu/24.11:v1 --view=modules - > module avail + ```console + $ uenv start prgenv-gnu/24.11:v1 --view=modules + $ module avail ---------------------------- /user-environment/modules ---------------------------- aws-ofi-nccl/git.v1.9.2-aws_1.9.2 lua/5.4.6 boost/1.86.0 lz4/1.10.0 @@ -373,13 +373,13 @@ By default, the modules are not activated when a uenv is started, and need to be kokkos-tools/develop superlu/5.3.0 kokkos/4.4.01 zlib-ng/2.2.1 libtree/3.1.1 - > module load cuda gcc cmake - > nvcc --version + $ module load cuda gcc cmake + $ nvcc --version nvcc: NVIDIA (R) Cuda compiler driver Cuda compilation tools, release 12.6, V12.6.77 - > gcc --version + $ gcc --version gcc (Spack GCC) 13.3.0 - > cmake --version + $ cmake --version cmake version 3.30.5 ``` @@ -401,7 +401,7 @@ The `uenv run` command can be used to run an application or script in a uenv env `uenv run` is more generic - instead of running a shell in environment, it takes the executable and arguments to run in the shell. The following commands are equivalent: - ```terminal + ```console # start a new bash shell in prgenv-gnu uenv start prgenv-gnu/24.11 # start a new bash shell in prgenv-gnu @@ -410,27 +410,27 @@ The `uenv run` command can be used to run an application or script in a uenv env !!! example "running cmake" Call `cmake` to configure a build with the `default` view loaded - ```terminal + ```console # run a command - > uenv run prgenv-gnu/24.11:v1 --view=default -- cmake -DUSE_GPU=cuda .. + $ uenv run prgenv-gnu/24.11:v1 --view=default -- cmake -DUSE_GPU=cuda .. ``` !!! example "running an application executable" Run the GROMACS executable from inside the `gromacs` uenv. - ```terminal + ```console # run an executable: - > uenv run --view=gromacs gromacs/2024:v1 -- gmx_mpi + $ uenv run --view=gromacs gromacs/2024:v1 -- gmx_mpi ``` !!! example "running applications with different environments" `uenv run` is useful for running multiple applications or scripts in a pipeline or workflow, where each application has separate requirements. In this example the pre and post processing stages use `prgenv-gnu`, while the simulation stage uses the `gromacs` uenv. - ```terminal + ```console # run multiple applications, one after the other, that have different requirements - > uenv run --view=default prgenv-gnu/24.11:v1 -- ./pre-processing-script.sh - > uenv run --view=gromacs gromacs/2024:v1 -- gmx_mpi $gromacs_args - > uenv run --view=default prgenv-gnu/24.11:v1 -- ./post-processing-script.sh + $ uenv run --view=default prgenv-gnu/24.11:v1 -- ./pre-processing-script.sh + $ uenv run --view=gromacs gromacs/2024:v1 -- gmx_mpi $gromacs_args + $ uenv run --view=default prgenv-gnu/24.11:v1 -- ./post-processing-script.sh ``` ## Building uenv diff --git a/docs/storage/object.md b/docs/storage/object.md index a06504e7..604b2d2f 100644 --- a/docs/storage/object.md +++ b/docs/storage/object.md @@ -140,11 +140,11 @@ ERROR: S3 error: 403 (SignatureDoesNotMatch) To fix this, it is necessary to edit the `.s3cfg` file, normally located in the user's home directory, and change the `signature_v2` setting to true. -``` -~ > cat .s3cfg | grep signature_v2 +```console +~ $ cat .s3cfg | grep signature_v2 signature_v2 = True -> s3cmd ls s3://test-bucket +$ s3cmd ls s3://test-bucket 2024-12-09 08:05 15 s3://test-bucket/file.txt ``` diff --git a/readme.md b/readme.md index 55e8e220..c10873bd 100644 --- a/readme.md +++ b/readme.md @@ -13,9 +13,9 @@ The source CSCS documentation [docs.cscs.ch](httpa://docs.cscs.ch) Clone this repository on your PC/laptop, then view the documentation in a browser run `./serve`: ```bash -> git clone git@github.com:${githubusername}/cscs-docs.git -> cd cscs-docs -> ./serve +git clone git@github.com:${githubusername}/cscs-docs.git +cd cscs-docs +./serve ... INFO - [08:33:34] Serving on http://127.0.0.1:8000/ ``` From 43022d2150966810bed0de3761439c88494c6b66 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Thu, 3 Apr 2025 10:02:46 +0200 Subject: [PATCH 2/4] Add code blocks information to style guide --- docs/contributing/index.md | 43 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e0a5a461..74aad312 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -228,3 +228,46 @@ They stand out better from the main text, and can be collapsed by default if nee This note is collapsed, because it uses `???`. If an admonition is collapsed by default, it should have a title. + +### Code blocks + +Use [code blocks](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) when you want to display monospace text in a programming language, terminal output, configuration files etc. +The documentation uses [pygments](https://pygments.org) for highlighting. +See [list of available lexers](https://pygments.org/docs/lexers/#) for the languages that you can use for code blocks. + +Use [`console`](https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer) for interactive sessions with prompt-output pairs: +````markdown +```console title="Hello, world!" +$ echo "Hello, world!" +Hello, world! +``` +```` + +The above becomes: + +```console title="Hello, world!" +$ echo "Hello, world!" +Hello, world! +``` + +!!! warning + `terminal` is not a valid lexer, but MkDocs or pygments will not warn about using it as a language. + The text will be rendered without highlighting. + +Note the use of `title=...`, which will give the code block a heading. + +!!! tip + Include a title whenever possible to describe what the code block does or is. + +If you want to display commands without that can easily be copied, use `bash` as the language. +````markdown +```bash title="Hello, world!" +echo "Hello, world!" +``` +```` + +The above becomes: + +```bash title="Hello, world!" +echo "Hello, world!" +``` From 194524bed205a11cdf8da8398324c19fbf225b36 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Thu, 3 Apr 2025 11:04:58 +0200 Subject: [PATCH 3/4] Update docs/guides/gb2025.md Co-authored-by: Ben Cumming --- docs/guides/gb2025.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/gb2025.md b/docs/guides/gb2025.md index 7ae29120..907b1520 100644 --- a/docs/guides/gb2025.md +++ b/docs/guides/gb2025.md @@ -42,7 +42,7 @@ This confines system processes and operations to the first core of each of the f The consequence of this setting is that only 71 cores per socket can be requested by an application (for a total of 284 cores instead of 288 cores per node). -!!! warning "Unable to allocate resources: Requested node configuration is not availabl" +!!! warning "Unable to allocate resources: Requested node configuration is not available" If you try to use all 72 cores on each socket, SLURM will give a hard error, because only 71 are available: ```console From 12475300572e16f29aac53be0a9653cf3ab652a5 Mon Sep 17 00:00:00 2001 From: Mikael Simberg Date: Thu, 3 Apr 2025 11:13:23 +0200 Subject: [PATCH 4/4] Update code blocks style guide --- docs/contributing/index.md | 52 +++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 21 deletions(-) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 74aad312..5a29d7f3 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -236,38 +236,48 @@ The documentation uses [pygments](https://pygments.org) for highlighting. See [list of available lexers](https://pygments.org/docs/lexers/#) for the languages that you can use for code blocks. Use [`console`](https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer) for interactive sessions with prompt-output pairs: -````markdown -```console title="Hello, world!" -$ echo "Hello, world!" -Hello, world! -``` -```` -The above becomes: +=== "Markdown" -```console title="Hello, world!" -$ echo "Hello, world!" -Hello, world! -``` + ````markdown + ```console title="Hello, world!" + $ echo "Hello, world!" + Hello, world! + ``` + ```` + +=== "Rendered" + + ```console title="Hello, world!" + $ echo "Hello, world!" + Hello, world! + ``` !!! warning `terminal` is not a valid lexer, but MkDocs or pygments will not warn about using it as a language. The text will be rendered without highlighting. +!!! warning + Use `$` as the prompt character, optionally preceded by text. + `>` as the prompt character will not be highlighted correctly. + Note the use of `title=...`, which will give the code block a heading. !!! tip Include a title whenever possible to describe what the code block does or is. -If you want to display commands without that can easily be copied, use `bash` as the language. -````markdown -```bash title="Hello, world!" -echo "Hello, world!" -``` -```` +If you want to display commands without output that can easily be copied, use `bash` as the language: -The above becomes: +=== "Markdown" -```bash title="Hello, world!" -echo "Hello, world!" -``` + ````markdown + ```bash title="Hello, world!" + echo "Hello, world!" + ``` + ```` + +=== "Rendered" + + ```bash title="Hello, world!" + echo "Hello, world!" + ```