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 git@github.com:path/to/my-repo.git
Download the appropriate patch file below by right-clicking the link
and choosing "Save page as...". Note that on Windows the file may be
saved with the .txt file extension, which means that you'll need to
modify the file name in the git apply command below.
| Template | Patch file |
|---|---|
| Markdown | fair4rs_config.patch |
| R Markdown | fair4rs_config_rmd.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:
titlecreatedkeywordssourcecontact
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.