arctraining/rc-slides

Public facing homepage for arctraining slides

Research Computing Slides

This is a repository for ARCTraining Quarto slides collection.

Repository Setup

This repository was created from Sparrow0hawk/quarto-revealjs-template.

This repository is used to publish a RevealJS website that has been written in Quarto. It includes a GitHub Action which will convert the Quarto source to HTML and publish them via GitHub Pages.

Its a useful way of making slides portable as they are then available via the URL and naturally the slides are version controlled.

Standard Presentation

A standard Research Computing presentation includes

• Title slide
• Team slide
• End slide
• Footer

The meta definition for a standard presentation is:

---
format: 
  revealjs:
    navigation-mode: linear
    controls-layout: bottom-right
    controls: true
    footer: "[Research IT Website]({{< var rc.website >}}) | [Research IT Query]({{< var rc.servicedesk >}}) | [Courses Material]({{< var rc.material >}})"
code: Course Code
name: Course Name
---

Note that code and name are meta variables used to generate the title slide (see below).

The Title Slide

The title slide is defined in the _title.qmd file, and is included in the presentation file via the {{< include _title.qmd >}} command. This slide has three elements:

• Title: value retrieved via meta.code
• Subtitle: value retrieved via meta.name
• Image

The title slide should looks like:

Tip: if you want to create a title slide without title or subtitle, you can leave the meta values for code or name empty.

The Team Slide

The team slide is defined in the _team.qmd file, and is included in the presentation file via the {{< include _team.qmd >}} command. This slide has two variables elements:

• Staff: value retrieved from _variables.yml file via {{< var rc.team >}}
• IT Servicedesk link: value retrieved from _variables.yml file via {{< var rc.servicedesk >}}

Tip: If any of these values needed to be updated, please do this via _variables.yml file, and then, all standard presentations are going to be automatically updated.

The team slide should looks like:

The End Slide

The end slide is defined in the _end.qmd file, and is included in the presentation file via the {{< include _end.qmd >}} command. This slide has three variables elements:

• IT Servicedesk link: value retrieved from _variables.yml file via {{< var rc.servicedesk >}}
• ARC Website: value retrieved from _variables.yml file via {{< var rc.website >}}
• HPC documentation: value retrieved from _variables.yml file via {{< var rc.documentation >}}

Tip: If any of these values needed to be updated, please do this via _variables.yml file, and then, all standard presentations are going to be automatically updated.

The end slide should looks like:

New Standard Presentation

To start a new standard presentation, start by creating a copy of the file template.qmd. Then, rename the new file using the training code, for example hpc0.qmd. Now, you will have to edit this new file and change the meta information (code and name) to reflect the training course content. For example, the meta for the HPC0 is:

---
format: 
  clean-revealjs:
    self-contained: true
    navigation-mode: linear
    controls-layout: bottom-right
    controls: false
    footer: "[Research IT Website]({{< var rc.website >}}) | [Research IT Query]({{< var rc.servicedesk >}}) | [Courses Material]({{< var rc.material >}})"
code: HPC0
name: Introduction to Linux for HPC

---

Done! The standard presentation is created. You can write the main content for the presentation by replacing the ## Slide A, ## Slide B and ## Slide C temporary content.

Write your slides

You are now ready to create your slides by editing the index.qmd in the root of the repository. For more information on writing RevealJS slides in Quarto see the RevealJS guide and the Revealjs Reference.

Preview locally

You'll need a working quarto. This can be installed from conda and you'll also want to install the theme extension:

conda create -n quarto -c conda-forge quarto
conda activate quarto
quarto install --no-prompt extension grantmcdermott/quarto-revealjs-clean

You can then preview this via:

quarto preview

Publish Locally

You will need to run quarto publish gh-pages once locally before deploying this template.

pre-commit

A basic pre-commit configuration is included (see .pre-commit-config.yaml) however to use it you will have to install pre-commit in your cloned repository. This requires pre-commit to be installed on your system or within a Python Virtual Environment. To find out more about installing and configuring pre-commit see the article pre-commit : Protecting your future self.

Extensions

There is a growing number of useful Quarto extensions.

QR Code generation

The quarto-qrcode extension is particularly useful as it simplifies generating and embedding QR Codes that link to websites in your slides.

rc-slides's Issues

Update Readme

Remove initial template content and include useful contribution/usage information

Java0

Add Introduction to Java Programming Course

Update HPC0

Update slides following latest run of the course. There are a few tweaks and additions that are wanted...

HPC0 slides

Transform old google slides into quarto slides

Update Theme

Theme Update

After we fix #16 the next step is apply the same Theme to all slides and verify if everything is working as expected:

• hpc0.qmd
• template.qmd
• index.qmd (?)

HPC0 Theme update

• Verify how every slides render with the new theme and tweak as necessary

Index

In my test, I found a possible problem with the index page.
I am not sure, but it seems that install a new theme may affect this page.

One possible solution if this happens is:

format:
  html:
    embed-resources: true

Update homepage

Update index.qmd file

• Fix Title
• Add description
• Add list of slides with links
• Add useful links

Create a template slide

To ensure that the slides have a minimum standardisation, create a template that will serve as the basis for all future slides:

The template must include

• Standard names
• footnote: GH link, material link, RC team homepage, RC ticket link (?)
• Set theme
• Standard page title
• If necessary: Custom style

Update HPC0 slides to fix some issues identified in the latest run of the training

Simplify the prompt to a $ with an explanation for readers.
Change "user" to "exuser" in examples for consistency
The Wildcards slide as an a type "0 or 1" should be "1 or 2".
Add some details for sharing files using getfacl and setfacl
In exercises remove the erroneous ">" which are confusing.

We could probably completely redo this image as our courses are quite different now but potentially a change unrelated to this PR. (Maybe an issue for revamping HPC0 slides?)

          We could probably completely redo this image as our courses are quite different now but potentially a change unrelated to this PR. (Maybe an issue for revamping HPC0 slides?)

Originally posted by @Sparrow0hawk in #6 (comment)

HPC1: quarto-revealjs-clean theme is not rendering

I believe if we add the self-contained option in the meta data it will solve the problem:

  clean-revealjs:
    self-contained: true # << add this line!
    navigation-mode: linear

HPC0 fixes following November 2023 session

pwd is a bad example of a command to use --help with, as it's a shell built in, and doesn't work on arc4. Should use ls --help instead?

donut

Add Resources section. Name donut presentation as a Speaker Guide. Update slides so they fit on a page. Maybe add another presentation for mermaid recipes.