Software Carpentry, and its umbrella organisationThe Carpentries develop excellent training material in research software skills for academia. A great deal of effort has been put into the training, particularly from the pedagogical side breaking down each lesson into modular episodes with clear learning objectives, highlighted sections on Key Points, Exericses, Solutions etc. Additionally all the material is available for general use under a CC BY 4 making it a fantastic resource for the community.
The lessons are written in decorated markdown which is built to generate a lesson website. The decoration can be minimal but is not entirely intuitive and certain compopnents require some care to prevent build issues. Some of the functionality also makes use of javascript which introduces a further language requirement if users want to explore the build system in depth. We wanted to use a similar design and richness of content, but with a simpler build to reduce dependencies and maximise the userbase ...
Advancing Research Computing we are currently developing a range of courses to support training for postgraduate researchers and staff. As a large number of these courses will use python we felt it sensible to use notebooks to produce the training material, since this allows code blocks and output to be included in material presented to students. We have also investigated creating bespoke magic for extending %bash and latex functionality. By adopting a format that is increasingly being used for teaching more generally we also felt that the tools might be useful for other courses.
Also we wanted to make use of Jupyter Notebooks for the training material due to the ability to mix code and use native mark-up (as far as possible), even when we would not intend to use Jupyter for the teaching itself. By doing so we aim to deliver a build system that was usable by anyone familar with notebooks and the linux command line, with as little decoration to Markdown as possible, producing content as rich and consistent with Software Carpentry material.
The build system uses Jupyter a small number of additional python libraries, and at present a few standard linux commands (e.g. make, sed). Much of the apparent complexity is in order to overcome current restrictions in the standard Jupyter workflow for generating different formats. Users create notebooks as they would normally except for using markdown decorated with a small number of key words. In the first part of the build, the notebooks_plain are pre-processed to create notebooks_rendered, which involves adding html to brand and enrich the notebooks.
These can then be converted to html using nbconvert after which a few sed commands make small adjustments to the content, e.g. changing file endings addresses to .html to preserve links and fix minor we have issues encountered. Finally these can then be build to pdf (currently subject to to an additional dependency). The end result is that users can readily build Notebooks for use by students or as slides for presentation, static webpages for a course as well as in printable form, from a single code base and with minimal admin. This is all presented within a template that helps to structure lessons and encourages the use of good educational practices.