This framework was created to accelerate the development of interactive tutorials. It combines a web browser with an scala REPL interpreter allowing for interactive code presentation and execution in the style of Jupyter Notebooks.
Go ahead and try to execute the code snippet below:
// Double-click this code box, or click the RUN button
// to execute this fragment.
// Alternatively, select the code and press ENTER to execute.
println("Hello World!")
To create a new tutorial, setup a new scala project and a dependency to [TBD].
Extend the trait ch.unibas.cs.gravis.tutorial.Tutorial
and specify its abstract members:
tutorialName
: The name of the tutorial displayed in the title bar.homeFile
: URL to the front-page of your tutorial.chapters
: List of URLs to the individual chapters of your tutorial.imports
: List of packages to import by default for interpreted code.URLs can be regular Links of the form http[s]://your.content/here
or /your/content/here
. The latter references files that are bundled in the tutorial application's resources. By omitting the leading /
it is possible to specify paths relative to the package of the currently executed class (usually the tutorial's main class).
If the Tutorial
-extension is declared as an object
it can be used as the main class of your application straight away, as the Tutorial
-trait provides an appropriate main
-method.
In order to populate your tutorial with content, you will need to create some HTML files. Although you could write them manually, it is recommended to use a tool to conveniently generate HTML from a different markup format. This demo page was written in Markdown and translated to HTML with Pandoc for instance.
If you are using SBT you can also use the Gravis Tutorial plugin for SBT (see next section). It can setup your project structure to an appropriate format, translate markdown files, automatically check tutorial code snippets and bundle resulting HTML files into the resources of your tutorial application.
If you happen to build your tutorial project with SBT, you might be interested in using the Gravis Tutorial for SBT. It automates the HTML generation from markdown files. It features a basic shortcode system that extend the markup format for easier code integration. Furthermore it provides methods for packaging the tutorial into an executable JAR (via sbt-assembly) and bundling the JAR with additional data folders into a ZIP for easy shipping. The plugin integrates seamlessly into existing SBT projects.
To create a new tutorial, simply add it as a dependency in your SBT project's project
folder by creating a file sbt-tutorial.sbt
with the following contents:
addSbtPlugin("ch.unibas.cs.gravis" % "sbt-tutorial-plugin" % version)
Additionally you need to specify the path to your local pandoc executable in your build.sbt
(if it is not included in you PATH environment variable):
pandocCmd := "./tools/pandoc/pandoc.exe"
When you compile the project, the tutorial plugin will transform any markdown files in src/main/tutorial
into HTML and copy the result to src/main/resources
from where it can be accessed by the tutorial code.
The task for compiling markdowns is called tutorialCompile
and it has a reverse-dependency to the standard compile
task. Hence it will be triggered when a standard compile
is executed via sbt.
Furthermore the tutorial files can be packaged into a ZIP file automatically with the command tutorialPackage
. It will generate a JAR file (using the sbt-assembly plugin) and bundle it with any specified data paths into a single ZIP file.
tutorialName
: The name that will be used for generated tutorial artifacts.tutorialMainClass
: Main class in the executable JAR.tutorialOutputPath
: Generated HTML goes here.tutorialPackageOutputFile
: File path of the final zipped tutorial artifact.tutorialDataInputPaths
: Additional data that will be bundled with the ZIP artifact.tutorialMarkdownTransformations
: Transformations that will be applied to each line of the markdown - used to implement shortcodes.The following shortcodes are enabled by default. They are defined in tutorial.MarkdownTransformations
which can accessed in build.sbt
via TutorialPlugin.markdownShortcodes
.
Code snippets can be copied from sources into markdown with the shortcode code_snippet
. It will copy lines following a specific label from sources into the generated HTML file.
The shortcode is used as follows (without brackets []
):
code_snippet [package.MyClass] [label]
where package.MyClass
is the fully qualified name of a class in the project's sources and label
refers to a label-comment in the in the class of the form // label [my label]
(without brackets).
Lines starting with ;;;;
will not be included in the generated HTML.
You can link to markdown files. The extension will be changed to .html
when the markdown files are transcribed to HTML.