Contributing
To contribute by creating a new workshop, please follow see the Contributing Instructions.
To create a Markdown-based workshop, use the Markdown template.
To create an RMarkdown-based workshop, use the RMarkdown template. RMarkdown workshops allow execution and compilation of code to render the final workshop website.
On the template repository, click "Use this template" on the top-right corner.
To develop a new workshop, you will need the following:
We recommend doing the following through conda/miniforge:
After that:
- Install RStudio
- On RStudio, install the
devtoolspackage:install.packages("devtools") - Install the
uom-varnishpackage:devtools::install_github("melbournebioinformatics/uom-varnish")
- Install the
sandpaper,pegboard, andtinkrpackages:install.packages( c("sandpaper", "pegboard", "tinkr"), dependencies = TRUE, repos = c(getOption("repos"), "https://carpentries.r-universe.dev") )
When in doubt, follow the Carpentries Workbench development guide, but note that we use the fork uom-varnish, rather than the original Carpentries varnish.
You should be good to go! ✅
To create a new workshop, select one of the two templates:
If you are workshop contains text only and minimal code, use the pure Markdown template. If your workshop contains code, plots, functions, and so on, use the RMarkdown template. It can accommodate other languages, eg Python.
When you have selected a template, click the "Use this template" and "Create a new repository" button on the top-right corner of the screen.
Select a name for your new workshop. We recommend names to be lowercase, with dashes (-) separating words. Picking a good name can be difficult, but a good guideline is to include the main topic, and either the focus or the technical level of the tutorial. In this case, we went with the latter, resulting in "intro-to-git" (technical level + main topic).
Your new workshop may be either public or private. You can create it as a private, and change it to public later after you've done some work on it.
After you've created your new repository, clone the repository locally:
After you've cloned the repository, open RStudio, go on "File" > "Open Project...", navigate to the repository you've cloned, and open the FIXME.Rproj file.
On RStudio, open a Terminal window and use Git to rename the project file to your repository name:
git mv FIXME.Rproj intro-to-git.Rproj
git commit -m "Rename Rproj"
git push
Double click the renamed project file on the "Files" pane in the bottom right to reload the project.
Run sandpaper::serve() on the RStudio console, and it should build the website and serve it at http://127.0.0.1:4321.
If you go to http://127.0.0.1:4321 on your browser, it should be displaying the workshop website.
You can now start working locally on this new workshop! ✅
There are a couple of things to know when working on a new workshop:
- the
config.yamlfile contains the main configuration for the workshop. This is a good starting point. Edit the FIXME values in this file to reflect your new workshop. - the
episodes/directory contains the bulk of content of the workshop. Most of the work will be done here. - Workshops, also referred to as "Lessons", are divided into episodes. Episodes are chunks of content that are used to structure the workshop. Episodes should be somewhere between 15-45 minutes long, and not longer than 60 minutes. Every episode should have questions, learning objectives, and keypoints that guide the content of the episode. The former two go at the start of the episode, and the latter goes at the end.
You don't have to worry about most of the other files for now. For a more comprehensive guide on how to develop lessons, see the links below: