diff --git a/.gitignore b/.gitignore index 84975854..0a68048f 100644 --- a/.gitignore +++ b/.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/* diff --git a/build.sbt b/build.sbt index ad9b7848..3f806e5c 100644 --- a/build.sbt +++ b/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: _*) diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 00000000..316e6fa0 --- /dev/null +++ b/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. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..c1d5595e --- /dev/null +++ b/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` + \ No newline at end of file diff --git a/docs/reference-config.md b/docs/reference-config.md new file mode 100644 index 00000000..359cda56 --- /dev/null +++ b/docs/reference-config.md @@ -0,0 +1,8 @@ +--- +id: reference-config +title: CMT configuration reference +sidebar_label: CMT configuration +--- + +# Configuration + diff --git a/docs/reference-delinearize.md b/docs/reference-delinearize.md new file mode 100644 index 00000000..a73c6ad3 --- /dev/null +++ b/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 + 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. + diff --git a/docs/reference-intro.md b/docs/reference-intro.md new file mode 100644 index 00000000..86a7e868 --- /dev/null +++ b/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 +__ 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 __ as a placeholder. + + + diff --git a/docs/reference-linearize.md b/docs/reference-linearize.md new file mode 100644 index 00000000..560bea7e --- /dev/null +++ b/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 + 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) diff --git a/docs/reference-mainadm.md b/docs/reference-mainadm.md new file mode 100644 index 00000000..38b77d91 --- /dev/null +++ b/docs/reference-mainadm.md @@ -0,0 +1,262 @@ +--- +id: reference-mainadm +title: cmt-mainadm Command Reference +sidebar_label: cmt-mainadm +--- +## Command Invocation + +``` +Usage: mainadm [options] mainRepo + + mainRepo base folder holding main course repository + -mjvm, --multi-jvm generate multi-jvm build file + -b, --build-file-regen regenerate project root build file + -d, --delete + -r, --renumber renumber exercises + -ro, --renumber-offset + renumber exercises - offset + -rs, --renumber-step + renumber exercises - step + -dib, --duplicate-insert-before + + -cfg, --config-file + configuration file + -c, --check-main-repo verify soundness of main repository + -amc, --add-main-commands + add command files to main repository + -t, --generate-tests-script + generate a script that tests main repo, studentified repo functionality and linearize/delinearize + -g, --init-studentified-test-repo-as-git + Generate studentified repo as a git repo in tests + -dot, --dotty studentified repository is a Dotty project + -nar, --no-auto-reload-sbt + no automatic reload on build definition change + --help Prints the usage text + -v, --version Prints the version info + ``` + +## Main administration tasks + +The `cmt-mainadm` command takes a single argument: the absolute path of the +CMT main repository. + +Depending on the action specified, the following options may apply: + +### `-dot`: Dotty compatible build definition + +With this option, the Scala version is assumed to be set exactly in the +`Version.scalaVersion` variable in your build definition. If this is not +the case, you will set the sbt build's `scalaVersion` settings elsewhere. + +### `-nar`: Do not automatically reload the build on build changes + +This option allows one to overrule the default behavior which is to +automatically reload the build when a change in the build definition +is detected by sbt. + +## Deleting an exercise + +The following command will delete the exercise with number `n` from the main +course repository and re-generate the root `build.sbt` file: + +``` +$ cmt-mainadm -d [-cfg config_file] [-dot] [-nar] +``` + +## Duplicate a given exercise and insert it before that exercise + +The following command will duplicate the exercise with number `n`. +The duplicate will retain the number of the exercise that is duplicated +while the latter and subsequent exercises to be shifted "down". + +``` +$ cmt-mainadm -dib [-cfg config_file] [-dot] [-nar] +``` + +For example, imagine a main repo with a list of exercises with exercise +numbers increasing by 1. The following table shows the before and after +when running the `cmt-mainadm -dib 3 ...` command: + +![DIB exercise # 3 - no gap](https://i.imgur.com/oSp1KXY.png) + +If there is "space" to insert the duplicate, no renumbering will occur as +the before and after shows when running the `cmt-mainadm -dib 6 ...` command: + +![DIB exercise # 3 - gap](https://i.imgur.com/CYJafQH.png) + +## Renumber exercises with a given offset and step size + +In some situations, it can be useful to renumber the exercises in a main +repository. Perhaps you want to create a "gap" in which some new exercises +will be put, or you want to shift all exercises to some offset. + +This can be achieved with the _renumber_ option on `cmt-mainadm`. + +Here are a couple of examples with a before and after situation. + +Running `cmt-mainadm -r -rs 5 -ro 10 ...` + +![Renumber with non-default offset and stepsize](https://i.imgur.com/pm7m6f9.png) + +Running `cmt-mainadm -r -rs 7 ...` + +![Renumber with non-default stepsize](https://i.imgur.com/URbqTV3.png) + +Running `cmt-mainadm -r -ro 10 ...` + +![Renumber with non-default offset](https://i.imgur.com/kBAaEaC.png) + +## Generation of a repository test script + +In the course of the life-time of a CMT project, the exercise series most +probably will change quite a bit by changing exercises, moving them around, +deleting and adding exercises and you may want to switch to a new version of +the CMT tools when it becomes available. + +You want to make sure that your project is still running fine: the code +compiles without errors and all tests pass for _**each and every**_ exercise. +Verifying this manually is tedious and error prone. + +The alternative is to automate the process and this can be done with the +help of `cmt-mainadm -t ...` + +Running: + +``` +cmt-mainadm -t [-cfg config_file] [-dot] [-nar] +``` + +will generate a script (with the file name passed as an argument to the `-t` option) +that, when executed, will run the following steps: + +- for each of the exercises in the main repository: + - compile the exercise code + - run the exercise tests + - run the `man e` command +- it _linearizes_ the main repository and it executes the test on the _last_ +exercise (at the HEAD of the **git** repo) +- it _studentifies_ the main repository and in this repo it runs through +_all_ the exercises in a random manner and for each of these exercise it: + - jumps to that exercise + - pulls the solution + - runs the tests + - saves the state + - lists the saved states + - restores the saved state + +Ideally, you should set-up CI/CD to perform this test process on each PR and +PR merge. For inspiration, you may want to have a look at +[the way this is done](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course/blob/main/.github/workflows/ci.yml) +via Github Actions in the Lunatech Labs [Moving from Scala 2 to Scala 3 Github +course](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course). + +## Checking the soundness of a CMT main repository + +A CMT main repository has to be built according to a number of conventions. +When building a new course, it may be difficult to check if all these +conventions are followed. `cmt-mainadm`'s _check main repository soundness_ +feature allows one to run a check of most of these conventions and report +any discrepancies. + +The following checks are made: + +- Presence of a global course instruction file (`README.md`) +- Presence of exercise instruction files (`README.md`) for all exercises +- Presence of a course name file (`.courseName`) +- Presence of a number of files in the sbt build definition: + - `CommonSettings.scala` + - `AdditionalSettings.scala` + - `CompileOptions.scala` + - `Dependencies.scala` + - `build.properties` +- Presence of the following files in the sbt build definition (note that in + some use cases however, these files may not be present): + - `Man.scala` + - `Navigation.scala` + - `MPSelection.scala` + - `StudentCommandsPlugin.scala` + - `StudentKeys.scala` +- Presence of a `common` project source folder in your build (unless your + project has a configuration that disables a `common` project). + +Here's an example of a run of `cmt-mainadm -c` that reports no problems: + +``` +$ cmt-mainadm -c /Users/ericloots/Trainingen/LBT/lunatech-scala-2-to-scala3-course +git version 2.28.0 +On branch main +Your branch is up to date with 'origin/main'. + +nothing to commit, working tree clean +CHECKING WORKSPACE in /Users/ericloots/Trainingen/LBT/lunatech-scala-2-to-scala3-course +Initialized empty Git repository in /private/var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_1166dfa5/lunatech-scala-2-to-scala3-course.git/ +To /var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_1166dfa5/lunatech-scala-2-to-scala3-course.git + * [new branch] HEAD -> 87A371C8-3255-45CA-8A9F-AE2C00564636 +Cloning into 'lunatech-scala-2-to-scala3-course'... +done. +No issues found in main project +``` + +> NOTE: `cmt-mainadm` requires your working directory to have no unstaged +> files and your staging area to be clean. If that condition is not met, +> resolve it before trying again + +## Rebuild the root `build.sbt` of a CMT main repository + +Whenever manual changes are made to the exercise names in the main repository, +the sbt build definition must be adapted to reflect this change. It is +recommended to use `cmt-mainadm` to do this and it is done with the following +command: + +``` +$ cmt-mainadm -b [-cfg config_file] [-dot] [-nar] +``` + +It is recommended to utilise this option only when other feaures of +`cmt-mainadm` cannot solve the task at hand. For example, this is the +case when the name of an exercise is changed (e.g. from, say +`exercise_007_given` to `exercise_007_given_keyword`) + +## Wrapping up + +It is worthwhile to give an example of specifying a non-default CMT +configuration file to round up this section. You may have to do this +in your CMT project is you put the `course-management.conf` file in a +non-default location. + +For the example, we use the CMT Github repository itself and we will +run `cmt-mainadm -c` on the templates. Here are a few sample runs: + +``` +$ cmt-mainadm -c -cfg course-templates/scala-cmt-template-common/course-management.conf /Users/ericloots/Trainingen/LBT/course-management-tools +git version 2.28.0 +On branch documentation +Your branch is ahead of 'origin/documentation' by 1 commit. + (use "git push" to publish your local commits) + +nothing to commit, working tree clean +CHECKING WORKSPACE in /Users/ericloots/Trainingen/LBT/course-management-tools +Initialized empty Git repository in /private/var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_eb5fc633/course-management-tools.git/ +To /var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_eb5fc633/course-management-tools.git + * [new branch] HEAD -> 657B1907-032F-4F8F-A2C0-D9FB64D5F1C4 +Cloning into 'course-management-tools'... +done. +No issues found in main project +``` + +``` +$ cmt-mainadm -c -cfg course-templates/dotty-cmt-template-common/course-management.conf /Users/ericloots/Trainingen/LBT/course-management-tools +git version 2.28.0 +On branch documentation +Your branch is ahead of 'origin/documentation' by 1 commit. + (use "git push" to publish your local commits) + +nothing to commit, working tree clean +CHECKING WORKSPACE in /Users/ericloots/Trainingen/LBT/course-management-tools +Initialized empty Git repository in /private/var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_a6f71ad9/course-management-tools.git/ +To /var/folders/rq/vhwkgm9x2rs33jl4t2x6t6jr0000gn/T/sbt_a6f71ad9/course-management-tools.git + * [new branch] HEAD -> 420D7B5A-7747-49AA-814A-EFACED193B9C +Cloning into 'course-management-tools'... +done. +No issues found in main project +``` \ No newline at end of file diff --git a/docs/reference-studentify.md b/docs/reference-studentify.md new file mode 100644 index 00000000..0737c1bc --- /dev/null +++ b/docs/reference-studentify.md @@ -0,0 +1,33 @@ +--- +id: reference-cmtstudentify +title: cmt-studentify Command Reference +sidebar_label: cmt-studentify +--- + +## Command Invocation + +``` +Usage: studentify [options] mainRepo out + + mainRepo base folder holding main course repository + out base folder for student repo + -mjvm, --multi-jvm generate multi-jvm build file + -fe, --first-exercise + name of first exercise to output + -le, --last-exercise + name of last exercise to output + -sfe, --selected-first-exercise + name of initial exercise on start + -cfg, --config-file + configuration file + -g, --git initialise studentified repository as a git repository + -dot, --dotty studentified repository is a Dotty project + -nar, --no-auto-reload-sbt + no automatic reload on build definition change + --help Prints the usage text + -v, --version Prints the version info +``` + +# Utilisation + +![studentify process](https://i.imgur.com/8gH7Y7a.png) diff --git a/images/Lin-Delin.graffle b/images/Lin-Delin.graffle index 303a1a07..0bdc7c8e 100644 Binary files a/images/Lin-Delin.graffle and b/images/Lin-Delin.graffle differ diff --git a/images/cmt-mainadm-samples-for-documentation purposes.xlsx b/images/cmt-mainadm-samples-for-documentation purposes.xlsx new file mode 100644 index 00000000..b8263bd5 Binary files /dev/null and b/images/cmt-mainadm-samples-for-documentation purposes.xlsx differ diff --git a/project/plugins.sbt b/project/plugins.sbt index ea3b551d..acf1eae9 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -1,2 +1,3 @@ addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "5.2.2") -addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.9.0") \ No newline at end of file +addSbtPlugin("com.eed3si9n" % "sbt-buildinfo" % "0.9.0") +addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.3" ) diff --git a/website/blog/2020-07-17-new-version-1.0.0.md b/website/blog/2020-07-17-new-version-1.0.0.md new file mode 100644 index 00000000..3d64b3cc --- /dev/null +++ b/website/blog/2020-07-17-new-version-1.0.0.md @@ -0,0 +1,52 @@ +--- +title: Hello world! new release 1.0.0 +author: Robin Raju +authorURL: http://twitter.com/rbn_raj +authorImageURL: https://avatars2.githubusercontent.com/u/8011082?v=4 +--- + +## Course Management Tools - 1.0.0 🎉 +This is the initial release of `Course Management Tools`, a set of command line tools to build and maintain training courses. +The packaged applications are: +- cmt-delinearize +- cmt-linearize +- cmt-mainadm +- cmt-studentify + +### Notable Changes +- Simple Installation +- Support for Scala 3 (Dotty), +- Play Framework support added + +### How To Install +- Download and unzip `course-management-tools.zip` +- Update system `PATH` to `course-management-tools/bin` 🚀 + +You may easily update your `PATH` using the following commands + +If you are using `zsh` +``` +echo -n 'export PATH=$PATH:[path to course-management-tools/bin]' >> ~/.zshrc +``` +or if you are using `bash` +``` +echo -n 'export PATH=$PATH:[path to course-management-tools/bin]' >> ~/.bash_profile +``` + +### Contributors + +`git shortlog -sn --no-merges 5a894d9..1.0.0` + +``` + 91 Eric Loots + 9 Robin Raju + 7 Wade Waldron + 1 Ignasi Marimon-Clos + 1 Ryan Case + 1 Sezer Akar + 1 Yury Gribkov + 1 Craig Pottinger + 1 patricenys + 1 Enno + 1 Eugene Yokota +``` diff --git a/website/core/Footer.js b/website/core/Footer.js new file mode 100644 index 00000000..c6f50926 --- /dev/null +++ b/website/core/Footer.js @@ -0,0 +1,77 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react'); + +class Footer extends React.Component { + docUrl(doc, language) { + const baseUrl = this.props.config.baseUrl; + const docsUrl = this.props.config.docsUrl; + const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`; + const langPart = `${language ? `${language}/` : ''}`; + return `${baseUrl}${docsPart}${langPart}${doc}`; + } + + pageUrl(doc, language) { + const baseUrl = this.props.config.baseUrl; + return baseUrl + (language ? `${language}/` : '') + doc; + } + + render() { + return ( + + ); + } +} + +module.exports = Footer; diff --git a/website/package.json b/website/package.json new file mode 100644 index 00000000..1f87392a --- /dev/null +++ b/website/package.json @@ -0,0 +1,14 @@ +{ + "scripts": { + "examples": "docusaurus-examples", + "start": "docusaurus-start", + "build": "docusaurus-build", + "publish-gh-pages": "docusaurus-publish", + "write-translations": "docusaurus-write-translations", + "version": "docusaurus-version", + "rename-version": "docusaurus-rename-version" + }, + "devDependencies": { + "docusaurus": "^1.14.4" + } +} diff --git a/website/pages/en/help.js b/website/pages/en/help.js new file mode 100644 index 00000000..2b790e46 --- /dev/null +++ b/website/pages/en/help.js @@ -0,0 +1,54 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react'); + +const CompLibrary = require('../../core/CompLibrary.js'); + +const Container = CompLibrary.Container; +const GridBlock = CompLibrary.GridBlock; + +function Help(props) { + const {config: siteConfig, language = ''} = props; + const {baseUrl, docsUrl} = siteConfig; + const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`; + const langPart = `${language ? `${language}/` : ''}`; + const docUrl = doc => `${baseUrl}${docsPart}${langPart}${doc}`; + + const supportLinks = [ + { + content: `Learn more using the [documentation on this site.](${docUrl( + 'doc1.html', + )})`, + title: 'Browse Docs', + }, + { + content: 'Ask questions about the documentation and project', + title: 'Join the community', + }, + { + content: "Find out what's new with this project", + title: 'Stay up to date', + }, + ]; + + return ( +
+ +
+
+

Need help?

+
+

This project is maintained by a dedicated group of people.

+ +
+ +
+ ); +} + +module.exports = Help; diff --git a/website/pages/en/index.js b/website/pages/en/index.js new file mode 100644 index 00000000..e5cd622b --- /dev/null +++ b/website/pages/en/index.js @@ -0,0 +1,212 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react'); + +const CompLibrary = require('../../core/CompLibrary.js'); + +const MarkdownBlock = CompLibrary.MarkdownBlock; /* Used to read markdown */ +const Container = CompLibrary.Container; +const GridBlock = CompLibrary.GridBlock; + +class HomeSplash extends React.Component { + render() { + const {siteConfig, language = ''} = this.props; + const {baseUrl, docsUrl} = siteConfig; + const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`; + const langPart = `${language ? `${language}/` : ''}`; + const docUrl = doc => `${baseUrl}${docsPart}${langPart}${doc}`; + + const SplashContainer = props => ( +
+
+
{props.children}
+
+
+ ); + + const Logo = props => ( +
+ Project Logo +
+ ); + + const ProjectTitle = props => ( +

+ {props.title} + {props.tagline} +

+ ); + + const PromoSection = props => ( +
+
+
{props.children}
+
+
+ ); + + const Button = props => ( + + ); + + return ( + + {/**/} +
+ + + + + + +
+ + ); + } +} + +class Index extends React.Component { + render() { + const {config: siteConfig, language = ''} = this.props; + const {baseUrl} = siteConfig; + + const Block = props => ( + + + + ); + + const FeatureCallout = () => ( +
+

Feature Callout

+ These are features of this project +
+ ); + + const LiveCoding = () => ( + + {[ + { + content: + 'Perform Live Coding without stress. Jump to known states' + + 'and save live changes for later reference', + image: `${baseUrl}img/undraw_dev_focus_b9xo.svg`, + imageAlign: 'left', + title: 'Live Coding with a Safety Net', + }, + ]} + + ); + + const DemosAndPOCs = () => ( + + {[ + { + content: + 'Build and Maintain non-trivial Demos or Proofs of Concept
and
decompose them in small steps', + image: `${baseUrl}img/undraw_product_teardown_elol.svg`, + imageAlign: 'right', + title: 'Build and Maintain Demos and Proofs Of Concept', + }, + ]} + + ); + + const TrainingCourses = () => ( + + {[ + { + content: + 'Build and maintain training course exercises in a repo and make them ' + + 'available in a classroom setting in a student-friendly format', + image: `${baseUrl}img/build.svg`, + imageAlign: 'right', + title: 'Build and Maintain Training Courses', + }, + ]} + + ); + + const Features = () => ( + + {[ + { + content: 'This is the content of my feature', + image: `${baseUrl}img/undraw_react.svg`, + imageAlign: 'top', + title: 'Feature One', + }, + { + content: 'The content of my second feature', + image: `${baseUrl}img/undraw_operating_system.svg`, + imageAlign: 'top', + title: 'Feature Two', + }, + ]} + + ); + + const Showcase = () => { + if ((siteConfig.users || []).length === 0) { + return null; + } + + const showcase = siteConfig.users + .filter(user => user.pinned) + .map(user => ( + + {user.caption} + + )); + + const pageUrl = page => baseUrl + (language ? `${language}/` : '') + page; + + return ( +
+

Who is Using This?

+

This project is used by all these projects

+
{showcase}
+ {/**/} +
+ ); + }; + + return ( +
+ +
+ {/**/} + {/**/} + + + + +
+
+ ); + } +} + +module.exports = Index; diff --git a/website/pages/en/users.js b/website/pages/en/users.js new file mode 100644 index 00000000..039dc39f --- /dev/null +++ b/website/pages/en/users.js @@ -0,0 +1,48 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react'); + +const CompLibrary = require('../../core/CompLibrary.js'); + +const Container = CompLibrary.Container; + +class Users extends React.Component { + render() { + const {config: siteConfig} = this.props; + if ((siteConfig.users || []).length === 0) { + return null; + } + + const editUrl = `${siteConfig.repoUrl}/edit/master/website/siteConfig.js`; + const showcase = siteConfig.users.map(user => ( + + {user.caption} + + )); + + return ( +
+ +
+
+

Who is Using This?

+

This project is used by many folks

+
+
{showcase}
+

Are you using this project?

+ + Add your company + +
+ +
+ ); + } +} + +module.exports = Users; diff --git a/website/sidebars.json b/website/sidebars.json new file mode 100644 index 00000000..058b3a0d --- /dev/null +++ b/website/sidebars.json @@ -0,0 +1,14 @@ +{ + "docs": { + "Getting Started": ["getting_started", "install"], + "Reference": ["reference-intro", + "reference-mainadm", + "reference-cmtstudentify", + "reference-linearize", + "reference-delinearize", + "reference-config"] + }, + "docs-other": { + "First Category": ["doc4", "doc5"] + } +} diff --git a/website/siteConfig.js b/website/siteConfig.js new file mode 100644 index 00000000..0f294981 --- /dev/null +++ b/website/siteConfig.js @@ -0,0 +1,107 @@ +// See https://docusaurus.io/docs/site-config for all the possible +// site configuration options. + +const repoUrl = 'https://github.com/eloots/course-management-tools' +// List of projects/orgs using your project for the users page. +const users = [ + { + caption: 'Alpakka', + // You will need to prepend the image path with your baseUrl + // if it is not '/', like: '/test-site/img/image.jpg'. + image: 'img/alpakka-icon.png', + infoLink: 'https://github.com/akka/alpakka', + pinned: true, + }, + { + caption: 'Lunatech "Moving from Scala 2 to Scala 3"', + // You will need to prepend the image path with your baseUrl + // if it is not '/', like: '/test-site/img/image.jpg'. + image: 'img/dotty-logo-white.svg', + infoLink: 'https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course', + pinned: true, + }, +]; + +const siteConfig = { + title: 'Course Management Tools', + tagline: 'A set of tools to build and maintain\ntraining courses, demos, and POCs.', + url: 'https://eloots.github.io', + baseUrl: '/course-management-tools/', + + // Documentation source files generated by mdoc + customDocsPath: "course-management-tools-docs/target/mdoc", + + // Used for publishing and more + projectName: 'course-management-tools', + organizationName: 'eloots', + + headerLinks: [ + {doc: 'getting_started', label: 'Docs'}, + { href: repoUrl, label: "GitHub", external: true }, + {blog: true, label: 'Blog'}, + ], + + // If you have users set above, you add it here: + users, + + /* path to images for header/footer */ + headerIcon: 'img/favicon.ico', + footerIcon: 'img/favicon.ico', + favicon: 'img/favicon.ico', + + /* Colors for website */ + colors: { + primaryColor: '#00B900', + secondaryColor: '#00A900', + }, + + /* Custom fonts for website */ + /* + fonts: { + myFont: [ + "Times New Roman", + "Serif" + ], + myOtherFont: [ + "-apple-system", + "system-ui" + ] + }, + */ + + // This copyright info is used in /core/Footer.js and blog RSS/Atom feeds. + copyright: `Copyright © ${new Date().getFullYear()} Course Management Tools`, + + highlight: { + // Highlight.js theme to use for syntax highlighting in code blocks. + theme: 'github', + }, + + // Add custom scripts here that would be placed in