Create documentation using mdoc and Docusaurus

.gitignore

@@ -46,3 +46,15 @@ out/
 
 # Play
 logs/
+
+# Docusaurus
+node_modules
+
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

build.sbt

@@ -5,11 +5,17 @@ lazy val `course-management-tools` =
       studentify,
       linearize,
       delinearize,
-      mainadm
+      mainadm,
+      docs,
     )
     .settings(CommonSettings.commonSettings: _*)
     .settings(skip in publish := true)
 
+lazy val docs = project
+  .in(file("course-management-tools-docs"))
+  .settings(moduleName := "course-management-tools-docs")
+  .enablePlugins(MdocPlugin, DocusaurusPlugin)
+
 lazy val core = project
   .in(file("core"))
   .settings(CommonSettings.commonSettings: _*)

docs/getting_started.md

@@ -0,0 +1,115 @@
+---
+id: getting_started
+title: Getting Started
+sidebar_label: Introduction
+---
+
+## A brief history of CMT (Course Management Tools)
+
+When I joined Lightbend in 2016, I started working on the Lightbend Training Courses. At that
+time the code for the exercises in each course were maintained in a **git** repository so that
+courses could be versioned. The problem however was that each exercise in a course was mapped
+to a commit in git. So, in a course with say, 15 exercises, the **git** repository would
+have 15 commits. That was very nice in principle, but it made it very difficult from a
+maintenance point of view: as soon as one updated an exercise, the only way to do this was
+to use **git** interactive rebasing. Doing so rewrites the history of the exercise repository
+which is pretty bad because:
+
+- if one wants to keep track of previous versions of a course, the best one can do is to save
+  that version in a separate branch
+- if people did a Pull Request (PR) on a particular version of the course, the interactive rebasing
+  editing approach renders the PR useless
+
+Duncan Devore, one of my Lightbend colleagues at that time had already made a few attempts at
+coming up with a more flexible approach. I picked up the thread and implemented a system that
+became the Course Management Tools. The main goals I set out to achieve were:
+
+- put all course exercises in a **git** repository, the so-called _Main Repository_ (_MR_), that
+  allows versioning of the exercises _without being forced_ to use interactive rebasing
+  when editing exercises
+- create a tool to derive an artifact from the _MR_ that is optimised for student usage:
+  - self-contained (i.e. not a git repository)
+  - embedded exercise instructions
+  - navigation of the exercises and automatically pull in tests
+  - allow the student to
+    - "pull" the reference solution for an exercise
+    - save the current state of an exercise
+    - restore a previously saved state of an exercise
+- create a tool that allows a course creator or maintainer to change exercises using **git**
+  interactive rebasing when this makes sense
+
+Over time, practical experience showed that there are other very useful use cases for the tooling.
+That's what is described in the following section
+
+## Why CMT?
+
+What do the following have in common?
+
+- *Build and maintain a series of exercises for a training course*:
+  - where each exercise builds on the previous one
+  - the exercise history is tracked using **git**
+  - the exercises can be converted in a artifact that gives students the
+    possibility to navigate the exercises, save the current state of
+    their work for each exercise, and, if needed, *pull* the solution
+    for an exercise
+- *Build and maintain a non-trivial sample application and*:
+  - decompose it in bite-sized steps that can be grasped by users who
+    are not yet comfortable with the used software libraries and/or
+    frameworks
+  - the application history is tracked using **git**
+  - the application can be converted in an artifact that can be used
+    to run the application at any of the intermediate steps in an
+    easy manner
+  - the application can be converted in an artifact that can be used
+    to inspect the code changes between consecutive steps
+- *Build and maintain code that will be used during a live-coding session*:
+  - maintain a series of "checkpoints"
+  - track the checkpoint history in **git**
+  - provide for a safetynet by allowing to revert to a checkpoint
+  - save any changes made during the session for later retrieval
+
+The answer to the question in the beginning of this section is that all 
+of the above features are offered by the Course Management Tools (**CMT**).
+
+## Overview
+
+The Course Management Tools use a command line interface with the
+following commands:
+
+- **cmt-mainadm**: as the name suggest, this command is used for administration
+  purposes, such as renumbering exercises, generating the root `build.sbt`
+  build definition file
+- **cmt-studentify**: this command is used to generate an artifact that is suited
+  for different purposes:
+  - in a teaching context, it will be used by students to:
+      - display course and exercise instructions
+      - navigate between different exercises
+      - pull in exercise specific tests
+      - pull the reference solution for an exercise if needed
+      - save the current state of an exercise
+      - restore a previously saved exercise state
+      - print the list of exercises and mark the current exercise
+  - in live coding sessions, the exact same features used in a learning
+    context allow one to
+      - quickly restore the code to for any checkpoint by pulling the solution
+        for it
+      - save the current state of a modified checkpoint for later retrieval
+
+- **cmt-linearize** & **cmt-delinearize**
+
+**cmt-linearize** is used to generate an artifact, named the *linearized repo*
+that is used to edit the code in exercises using **git** interactive rebasing.
+Once the edit process is finished, **cmt-delinearize** is used to reflect the
+changes in the *linearized repo* in the main exercise repository.
+
+In general, the _linearized repo_ can be considered to be a scratch pad that is
+discarded after the editing process is finished. However, it can used to inspect
+the differences between consecutive exercises (this is because the linearized repo
+is a **git** repository where each exercise is a commit).
+
+The following picture shows the different respositories and flows in the management of a course.
+
+![CMT overview](https://i.imgur.com/5FzwpLa.png)
+
+It is the _Main Repository_ that contains the history of a course (or demo/POC) repository.
+The _Main Repository_ is multi-project sbt build with one project per exercise.

docs/install.md

@@ -0,0 +1,36 @@
+---
+id: install
+title: Installing Course Management Tools
+sidebar_label: Installation
+---
+
+## Supported Operating Systems and Prerequisites
+
+### Supported OS
+
+The Course Management Tools have been tested on the following Operating Systems:
+
+- MacOS 10.14 or higher
+- Ubuntu 18.04.4 LTS (tested via CI/CD)
+
+### Prerequisites
+
+Make sure to have a [recent version of **git**](https://git-scm.com/downloads) installed on your system.
+
+## Installation
+
+The preferred way to install the Course Management Tools is to download
+the binaries from [the latest release](https://github.com/eloots/course-management-tools/releases).
+
+The installation procedure is rather straightforward:
+
+- download the `course-management-tools.zip` file from the release page
+- unzip the content in a folder
+- update your PATH to include the `course-management-tools/bin` folder in
+  the folder in which you unzipped the downloaded zip file
+- You now have access to the following CMT commands:
+  - `cmt-mainadm`
+  - `cmt-studentify`
+  - `cmt-linearize`
+  - `cmt-delinearize`
+

docs/reference-config.md

@@ -0,0 +1,8 @@
+---
+id: reference-config
+title: CMT configuration reference
+sidebar_label: CMT configuration
+---
+
+# Configuration
+

docs/reference-delinearize.md

@@ -0,0 +1,32 @@
+---
+id: reference-delinearize
+title: cmt-delinearize Command Reference
+sidebar_label: cmt-delinearize
+---
+
+# Command Invocation
+
+```
+Usage: cmt-delinearize [options] mainRepo linearRepo
+
+  mainRepo                 base folder holding main course repository
+  linearRepo               linearized version repo
+  -cfg, --config-file <value>
+                           configuration file
+  --help                   Prints the usage text
+  -v, --version            Prints the version info
+```
+
+# Utilisation
+
+After having gone through one or more rounds of **git** interactive rebasing
+on a linearized repository, we can apply these changes on the main
+repository via a process of de-linearization as depicted here: 
+
+![Delinearize process](https://i.imgur.com/BYlAaPh.png)
+
+> IMPORTANT NOTE: `cmt-delinearize` will only write modifications applied
+> in the `exercises` project. Any other changes will be discarded. If you
+> want to change any other file, apply these changes directly on the main
+> course repo.
+

docs/reference-intro.md

@@ -0,0 +1,37 @@
+---
+id: reference-intro
+title: Introduction
+sidebar_label: Introduction
+---
+
+In this section you will find the CMT reference documentation. The
+behaviour of the CMT commands can be controlled in two ways:
+
+Each CMT command has a number of:
+
+- command line options that control its function
+  and behaviour
+- settings that are controlled via a 
+  configuration file. A complete overview of all the available
+  settings can be found in the
+  [CMT configuration section](reference-config.md). If there's
+  a configuration file named `course-management.conf` in the
+  main course repository's root folder, CMT command will apply
+  the settings provided in that file. One can also pass an
+  alternative configuration file to a CMT command with the `-cfg`
+  option. The path of the passed in configuration file is
+  relative to the main course repository's root folder.
+
+### Note
+
+All Course Management Tools commands take as first argument
+the _absolute_ path to the **_root_** folder of the **git** main
+course repository. In examples in this section, we will use
+_<main_repo>_ as a placeholder.
+
+`cmt-delinearize` takes as second argument the _absolute_ path to
+the folder containing the delinearized artifact. In examples in
+this section, we will use _<linearized_repo>_ as a placeholder.
+
+
+

docs/reference-linearize.md

@@ -0,0 +1,30 @@
+---
+id: reference-linearize
+title:  cmt-linearize Command Reference
+sidebar_label: cmt-linearize
+---
+
+## Command Invocation
+
+```
+Usage: linearize [options] mainRepo linearRepo
+
+  mainRepo                 base folder holding main course repository
+  linearRepo               base folder for linearized version repo
+  -mjvm, --multi-jvm       generate multi-jvm build file
+  -f, --force-delete       Force-delete a pre-existing destination folder
+  -cfg, --config-file <value>
+                           configuration file
+  -dot, --dotty            studentified repository is a Dotty project
+  -nar, --no-auto-reload-sbt
+                           no automatic reload on build definition change
+  -m, --bare-lin-repo      create a linearized repo without any of the CMT plugin functionality
+  --help                   Prints the usage text
+  -v, --version            Prints the version info
+```
+
+# Utilisation
+
+![Linearize process](https://i.imgur.com/hsJy9ZT.png)
+
+![Interactive rebasing process](https://i.imgur.com/z7N2Z4J.png)