UQ Library technology training resources

Source code for the UQ Library Technology Training website, on which you can find the material (and links to files) for our technology training sessions. Go to the website for a convenient listing of resources.

The website is built using Quarto.

Format of training sessions

Most sessions are designed to be hands-on.

All programming sessions use the "live-coding" format in which the instructor and the attendees type and execute commands together. A collaborative online pad (e.g. Etherpad, CryptPad and HedgeDoc) can be used to list useful links, challenges, and to interact during the session.

Archive

The following sessions are not currently maintained.

Title	Course notes	Live collaborative pad
Introduction to R for Humanities	md source	html

Licence

All of the information on this repository (https://github.com/uqlibrary/technology-training) is freely available under the Creative Commons - Attribution 4.0 International Licence. You may re-use and re-mix the material in any way you wish, without asking permission, provided you cite the original source. However, we'd love to hear about what you do with it!

Part of this repository is based on Paula Andrea Martinez's work available under the same CC-By-4.0 licence.

If you would like to develop on top of this, please cite the source as mentioned above, and conserve the git history if possible (so authors are credited).

Automation

The _processing folder contains some scripts which run during before and after render, and change depending on whether the render occurs locally or during CI (i.e. the GitHub workflow). Specifically:

During local renders

• Preprocessing checks all links across the repo and records their status (OK, CHECK, BROKEN, EXEMPT, VALID on ...) in ok_links.csv and check_links_log.csv. Manually validated links can be updated in validated_links.csv.
• Postprocessing does nothing.

During workflow renders

• Preprocessing injects banners onto all .qmd files which are associated with upcoming, advertised training. This has the unfortunate consequence of requiring those files to re-render, regardless of the state in _freeze.
• Postprocessing removes banners from files.

Note that all changes made during workflow renders occur on the runner, none of which are actually commited to the repo.

Contributing

You can raise an issue or submit a change in this repository if you spot something that needs fixing.

To modify lesson materials:

Uploading binary files (e.g. .pdf, .docx, .xlsx etc.)

Binary files are usually kept in a separate "assets" repository.

1. Go to the appropriate folder in the assets repository
2. Press "Add file" > "Upload files"
3. Choose the file, include an appropriate message (e.g. "Updated excel notes") and press "Commit changes"

To update a file, make sure the file name and location are the same. Otherwise, the website will still link to the old file.

If you've used a new name, or are uploading a new file, you will also need to update the website by changing the corresponding .qmd file's link.

Updating the website

1. Modify the corresponding Quarto (qmd) file.
2. Preview the website locally to see the changes:

quarto preview <path/to/the_source.qmd>

(Alternatively, click "Render" in the "Build" tab of RStudio, or "Preview" in Positron.)

3. Once you are happy with the changes, commit and push them to this repository.

If you have questions about contributing to the material, please contact the UQ Library.

The freeze: auto setting

This website uses the [freeze: auto](https://quarto.org/docs/projects/code-execution.html#freeze) setting in the _quarto.yml file. This means that when the website is rendered, only the files that have been modified are re-rendered, whereas the others use the previously rendered files stored in the _freeze directory. This helps with:

• reducing rendering times significantly (for contributors as well as the GitHub workflow), and
• making sure pages don't break when using a system that is not capable of rendering the whole website (packages not installed, dependency on older versions...).

When rendering locally after a change, the files in the _freeze directory will likely change, so make sure to commit those changes too.

Managing dependencies

We use {renv} for managing R dependencies and requirements.txt (with {venv}) for Python. If your contributions need new or updated packages, you'll need to update these dependencies.

Before you do, some things to consider:

• The website uses an Ubuntu runner. Some Python and R packages are specific to Windows/MacOS, so please ensure that the packages you are updating are required for Ubuntu.
• You will need to use virtual environments. Specifically, your clone of this repo should use Python/R environments that have the same dependencies (and no more) as specified in lock.file (R) or requirements.txt (Python). Once the clones are actually clones, you can then start to add new dependencies as required.
• Please ensure you only install what is necessary! There are too many dependencies already.

{renv} for reproducibility with R

The {renv} package is used to keep track of what R package versions were used to run the chunks of code. This can have several benefits:

• More consistency between systems that render
• More reproducibility, as we know which package version were successfully used when rendering a page

However, this means that one should remember to:

• run renv::restore(clean = TRUE) before making changes to code in the R lessons, so your local package versions match what is currently used (and so unused packages are removed)
• run renv::snapshot() to update the renv.lock file if packages had to be updated or new packages had to be installed.

If a package dependency is not caught automatically by {renv} (for example, if a function depends on an optional package), you can manually add it to the _dependencies.R file.

Make sure to commit any changes to renv.lock and _dependencies.R.

requirements.txt for reproducibility with Python

This repository also comes with a requirements.txt file for Python reproducibility. This file keeps track of Python dependencies which are used during website rendering.

If your changes require new Python packages, be sure to include these in the requirements.txt file.

To update the requirements.txt file, use a virtual environment manager. We recommend venv.

1. Make a clean Python environment in your local clone of the repo. Do not check this into version control: ensure the folder is in .gitignore.
2. Install the packages in requirements.txt (typically via pip install -r requirements.txt)
3. Install any other packages you require if you still need to (typically via pip install ...)
4. Update requirements.txt (typically via pip freeze > requirements.txt).
5. Commit any changes to requirements.txt. Do not commit any {venv} related files.

Captions and alternative text for images

For images that are not generated by code, you can use this syntax for caption and alternative text:

![Caption goes here](picture.png){fig-alt="Alternative text goes here"}

If the image (a graph, for example) is generated by a code chunk, use the chunk options fig-cap and fig-alt:

```{language}
#| fig-cap: "Caption goes here"
#| fig-alt: "Alternative text goes here"
Executable code goes here
```

Learn more about alt text:

• alt text in Quarto
• Wikipedia's guide on alt text
• Wikipedia's example of alt text
• Amy Cesal's article on writing alt text for data visualisation

Contact

If you are part of the UQ community, you can contact the technology trainers for a 1-on-1 consultation, an enquiry about sessions, or any question about the software supported by the UQ Library: training_{<commercial at>}library.uq.edu.au