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:
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.gitDownload 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.patchIf 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 applyPlease let us know by creating an issue including details of the error message.
.Rproj fileRename FIXME.Rproj to match your repo name:
git mv FIXME.Rproj my-repo.Rprojconfig.yamlThis 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:
titlecreatedkeywordssourcecontactFor 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.
CITATION.cffThis file contains information about citing this repository. At a
minimum, you should adjust all the fields marked # FIXME:
CONTRIBUTING.mdUpdate links to GitHub repository and issues, marked #FIXME.
LICENSE.mdReview the licence text and add references/attribution to any derived
material as indicated by the # FIXME comment.
README.mdReplace the setup information in your repository's README with relevant information about your lesson.
git add -u
git commit -m "Update configuration"
git pushTo 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:
6c36cf33f304afCreative 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.