Instructions for setting up a lesson repository for the University of Sheffield FAIR for Research Software training programme.

These instructions assume that you are familiar with following command line instructions. Please contact RSE-Sheffield if you require any support with lesson setup.

The Carpentries Workbench provides a standardised lesson format which we are using for the University of Sheffield FAIR for Research Software training programme. The lesson content is written as markdown or R Markdown and rendered using R and pandoc. Lessons can be developed within the RStudio IDE) or any other IDE (e.g. Emacs).

We use a custom fork of {varnish} from The Carpentries Workbench to apply University of Sheffield branding to the lesson theme and to add relevant links to training resources to the page footer.

Required software:

• git (>= 2.28 recommended)
• R (>= 3.6)
• pandoc (>= 2.11) (available through the RStudio IDE)

Please refer to The Carpentries Workbench installation instructions for setting up your lesson development environment.

If you choose to use R Markdown in your lesson then you will need the {rmarkdown} package, which should be installed as a dependency of the {sandpaper} package by following the instructions above.

To enable the custom theme to be applied when rendering the site locally, please refer to the following instructions for installing uos-varnish.

To create a new lesson repository, make sure you're logged into GitHub.

The Carpentries Workbench Template is available as a markdown lesson template or an R Markdown lesson template. In the R Markdown version the example episode is written in R Markdown and contains an example of dynamic content generated using R, while the markdown version contains static content only.

Visit https://github.com/carpentries/workbench-template-md/generate (markdown) or https://github.com/carpentries/workbench-template-rmd/generate (R Markdown) and follow the instructions to generate a lesson repository from the Carpentries Workbench Template. Checking the 'Include all branches' option will save some time waiting for the first website build when your new repository is initialised.

Clone the lesson repository to a suitable location on your local computer:

cd my-lesson-directory
git clone [email protected]:path/to/my-repo.git

Download fair4rs_config.patch.

Apply the patch file to the lesson repository:

cd my-repo
git apply --index path/to/fair4rs_config.patch

If the patch does not apply cleanly you may see an error message such as:

error: patch failed: config.yaml:17
error: config.yaml: patch does not apply

Please let us know by creating an issue including details of the error message.

Rename FIXME.Rproj to match your repo name:

git mv FIXME.Rproj my-repo.Rproj

This file contains global parameters for your lesson site. Individual fields within the file are documented with comments (beginning with #). At a minimum, you should adjust all the fields marked # FIXME:

• title
• created
• keywords
• source
• contact

For the created field you can enter the current date but typically you should adjust this to reflect the date on which you complete preparing the material.

This file contains information about citing this repository. At a minimum, you should adjust all the fields marked # FIXME:

• title
• authors (given name, family name, email, affiliation, orcid)
• repository-code
• url
• abstract
• keywords

Update links to GitHub repository and issues, marked #FIXME.

Review the licence text and add references/attribution to any derived material as indicated by the # FIXME comment.

Replace the setup information in your repository's README with relevant information about your lesson.

git add -u
git commit -m "Update configuration"
git push

To complete the setup of your lesson, follow the remaining instructions given in Configure a new lesson:

Navigate to Settings, select Pages from the left sidebar, and make sure that the Source is Deploy from branch (the default) and gh-pages is selected as the branch to build from. If no gh-pages branch is available, check Actions to see if the first website build workflows are still running. The branch should become available when those have completed.

Once you've activated GitHub Pages, content pushed to the repository will be deployed automatically by GitHub Actions. You can view the lesson website at https://username.github.io/my-repo/.

Navigate to the repository landing page and click on the gear wheel/cog icon at the top-right of the About box. Check the "Use your GitHub Pages website" option, and add some keywords and other annotations to describe your lesson in the Topics field.

Please refer to the Introduction to The Carpentries Workbench for further documentation.

The lesson setup process has been tested with the following revisions of the Carpentries Workbench Template:

• workbench-template-md: 6c36cf3
• workbench-template-rmd: 3f304af

Creative Commons Attribution 4.0 International

This work is derived from material in the Carpentries Workbench Template, which is Copyright (c) The Carpentries and is made available under the Creative Commons Attribution licence. Changes have been made to adapt the instructions for using the Carpentries Workbench Template in the specific context of the University of Sheffield's FAIR for Research Software training programme.