test and tutor maven mojos documented

courses/GettingStarted/MavenPlugin/MavenPlugin.md

@@ -16,12 +16,15 @@ The [rascal-maven-plugin](http://github.com/usethesource/rascal-maven-plugin) of
 * ((PackageMojo)) for packing compiled Rascal code, source code and documentation into a jar file. 
 * ((ExecMojo)) for executing arbitrary Rascal code during an arbitrary Maven goal.
 * ((ConsoleMojo)) for starting a Rascal ((REPL))
+* ((TestMojo)) for running Rascal tests.
 
-Each of the above is configured in XML in the local `pom.xml` file of a Rascal project. All of them are executed during a `mvn package` or `mvn install` commandline. If the local pom has the right configuration, then each mojo can also be invoked separately:
-* `mvn rascal:compile` runs the compiler and `-Drascal.compile.skip` guarantees it is skipped.
-* `mvn rascal:tutor` runs the tutor compiler and `-Drascal.tutor.skip` guarantees it is skipped.
-* `mvn rascal:package` runs the package rewriter and `-Drascal.package.skip` guarantees it is skipped.
+Each of the above is configured in XML in the local `pom.xml` file of a Rascal project. All of them are executed during a `mvn package` or `mvn install` commandline. If the local pom has the right configuration, then each mojo can also be invoked by the respective stage, or separately:
+* `mvn compile` or `mvn rascal:compile` runs the compiler and `-Drascal.compile.skip` guarantees it is skipped.
+* `mvn compile` or `mvn rascal:tutor` runs the tutor compiler and `-Drascal.tutor.skip` guarantees it is skipped.
+* `mvn package` or `mvn rascal:package` runs the package rewriter and `-Drascal.package.skip` guarantees it is skipped.
 * `mvn rascal:exec` executes some Rascal code, while `-Drascal.exec.skip` makes sure this goal is skipped.
+* `mvn test` or `mvn rascal:test` runs all test in all modules and reports the result in `target/rascal-test-results`, while `-Drascal.test.skip` makes sure this goal is skipped.
+* `mvn rascal:console` starts up a Rascal terminal with the same configuration as `mvn rascal:test` would use.
 
 #### Examples
 
@@ -46,3 +49,7 @@ newRascalPomFile(|tmp:///my-project|);
 * All dependencies defined in the `pom.xml` are used to automatically configure the library path of the compiler and the interpreter, as well as the classpath of the compiled or interpreted runtime engine.
 * Rascal projects can depend on any other Maven project
 
+#### Pitfalls
+
+* Watch out that `<configuration>` tags can be different for each `<execution>` goal. Specifically `<srcs>` can be (should be) different between compile and tutor.
+* Maven will always executer earlies stages first. So `mvn package` will execute `compile`, `test` and `package` (at least). Use `-Drascal.<stage>.skip` to avoid double work.

courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md

@@ -8,7 +8,7 @@ Prepare compiler output files for distribution in a jar file, and downstream usa
 
 #### Description
 
-The `prepare` plugin takes care of:
+The `package` plugin takes care of:
     * copying source files to the target folder, for later reference by debuggers (source distribution)
     * renaming file references in generated code and interface files (`.tpl` and `.constant`) such that they point to the distributed location and not the source project location.
 

courses/GettingStarted/MavenPlugin/TestMojo/TestMojo.md

@@ -0,0 +1,93 @@
+---
+title: Test Mojo
+keywords:
+    - unit test
+    - mvn test
+---
+
+#### Synopsis
+
+`mvn test` runs all rascal test functions in all Rascal modules that reachable from the configured source folders.
+
+#### Description
+
+If you add a test execution to the pom configuration:
+* then `mvn test` will run all available tests.
+* in interactive mode a progress bars are shown per module and for all modules.
+* in `target/rascal-test-reports`, each JSON file reports on one module.
+
+For example:
+```
+<plugin>
+    <groupId>org.rascalmpl</groupId>
+    <artifactId>rascal-maven-plugin</artifactId>
+    <version>0.32.0</version>
+    <configuration>
+        <bin>${project.build.outputDirectory}</bin>
+        <srcs>
+            <src>${project.basedir}/src</src>
+        </srcs>
+    </configuration>
+    <executions>
+        <execution>
+            <id>default-compile</id>
+            <phase>compile</phase>
+            <goals>
+                <goal>compile</goal>
+            </goals>
+        </execution>
+        <execution>
+            <id>default-test</id>
+            <phase>test</phase>
+            <goals>
+                <goal>test</goal>
+            </goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+Additionally you can configure parallel test execution like so:
+```
+<configuration>
+    <parallel>true</parallel>
+    <parallelMax>10</parallelMax>
+    <parallelPreChecks>
+        <check>${project.basedir}/src/MyInitialTests.rsc</check>
+    </parallelPreChecks>
+</configuration>
+```
+
+The `parallelPreChecks` are optional. They can be used to trigger basic tests first; if those fail it does not make much
+sense to try the other tests.
+
+#### Benefits
+
+* runs the Rascal tests exactly in the same context as the REPL on the terminal, so if you need to debug all you have to do is start a repl using VScode or `mvn rascal:console` and import the failing module.
+* outputs JSON test reports directly used by the github action `ctrf-io/github-test-reporter@v1`
+
+Example github action:
+
+```
+    - name: Publish Test Reports
+        if: ${{ !cancelled() }}
+        uses: ctrf-io/github-test-reporter@v1
+        with:
+          report-path: 'target/rascal-test-reports/*.json'
+          github-report: true
+          file-report: true
+          pull-request-report: true
+          summary-delta-report: true
+          insights-report: true
+          fail-rate-report: true
+          slowest-report: true
+          upload-artifact: true
+    env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Pitfalls
+
+* Uses the interactive progress bar by default, which would spam a build log with a line for every update. 
+   * Use `mvn -B` or `mvn -Drascal.monitor.batch` to turn off the progress bar in CI environments
+   * Also if there is an environment variable named `CI` the progress bar will be turned off (as is the case for GitHub actions)

courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md

@@ -4,8 +4,80 @@ title: Tutor Mojo
 
 #### Synopsis
 
-Compiles tutor markdown files in a specific folder hierarchy, and Rascal modules from source folders to a comprehensive collection of documentation files in markdown format.
+Compiles [tutor]((course:Tutor)) markdown files in a specific folder hierarchy, and Rascal modules from source folders to a comprehensive collection of documentation files in markdown format.
 
 #### Description
 
-(((TODO)))
+Just run `mvn compile` or `mvn rascal:tutor` to compile the documentation 
+in the current project. The resulting documentation in docusaurus Markdown format is packaged in the
+jar file under `/docs/Packages/<groupId>.<artefactId>/` for later processing in a website or an IDE. This includes:
+* one folder for every course sourced in `<srcs>`, recursively every concept file leads to a new folder and a new index file.
+* one folder for every module folder in `<srcs>`, recursively every module becomes one markdown file and every folder becomes a nested folder. See ((DocumentingCode)) for more information.
+* [screenshots](Tutor:Markup-Screenshots) made by the tutor pages are saved in the target folder
+
+When embedded executable code in .rsc modules or .md concept files fails unexpectedly, the `mvn rascal:tutor` build fails with an error message. The same holds for missing or ambiguous links.
+
+[Linking](Tutor:Markup-Links) concepts is possible between concepts and modules within the same project, _and_ between any project that links to a concept in a depending project (see `<dependencies>` in the pom.xml.
+
+The tutor may have its own configuration in an `<execution>` block. This is used to add course material next to the module API, or to remove the module API from the documentation entirely. For example:
+
+```
+<execution>
+    <id>default-cli</id>
+    <phase>compile</phase>
+    <goals>
+        <goal>tutor</goal>
+    </goals>
+    <configuration>
+        <bin>${project.build.outputDirectory}</bin>
+        <sources>|http://github.com/myOrg/myProject/blob/main|</sources>
+        <issues>|http://github.com/myOrg/myProject/issues|</issues>
+        <srcs>
+            <src>${project.basedir}/src</src>
+            <src>${project.basedir}/doc/Motivation</src>
+            <src>${project.basedir}/doc/References</src>
+        </srcs>
+    </configuration>
+</execution>
+```
+
+See ((course:Tutor)) for more information on how annotated Rascal modules and
+concept files in markdown format are used to compile documentation.
+
+This is the complete list of tutor parameters and their defaults:
+
+| parameter | example/default | note |
+| --- | --- | --- |
+| bin | `./target/classes/` | target folder where `docs` will reside |
+| srcs | `<src>./src/main/rascal</src>` | list of local source folders for Rascal modules and concept files |
+| ignores | `<ignore>./src/main/rascal/prelude</ignore>` | will not generate any documentation reachable from this folder |
+| sources | `http://github.com/usethesource/${project.name}/blob/main` | website of the project's home. |
+| issues | `http://github.com/usethesource/${project.name}/issues` | website of the project's issue tracker. |
+| license | ./LICENSE.md | local file that contains the (open-source) license. |
+| citation | ./CITATION.MD | local file that explains how to cite this project. |
+| funding | ./FUNDING.MD | local file that documents the money sources. |
+| authors | ./AUTHORS.MD | local file that explains authorship of the code in this project. |
+| version | `${project.version}` | the current version of this project. |
+| releaseNotes | ./RELEASE-NOTES.md | the release notes in inverse chronological order. |
+| isPackageCourse | true | stores output in `/docs/Packages/<groupId>.<artefactId>`, or in `/docs/<CourseName>` when `false`. |
+| includeLibraries | false | when true copies the libraries we depend on from `Library.jar!/docs/*` to `/docs/*`
+| errorsAsWarnings | false | when true will not fail the build even if errors are present |
+| warningsAsErrors | false | when true will fail the build even if only warnings are reported |
+
+Note that issues, license, citation, funding, authors and releaseNotes files must exist or else the build will fail.
+
+### Benefits
+
+* Using the tutor it is easy to create beautiful documentation that integrates seemlessly into http://www.rascalmpl.org
+* Writing  ((CodeExamples)) is a way to write documented tests. At compile-time all examples are tested for unexpected failures.
+* The tutor compiler is incremental. Repeated `mvn rascal:tutor` will only re-index and re-compile changed files.
+* The tutor compiler generates errors with accurate file names and line numbers, for easy fixing.
+* Every library package is always documented online with the relevant documentation on licenses, authors, funding, citation, API and
+specific user documentation.
+
+### Pitfalls
+
+* By default the tutor generates markdown in `/Packages/<groupId>.<artefactId>` and all links are relative to these subfolder.
+* The incremental compiler never removes information from the index. So after `mvn clean` new broken links can be found.
+* There is no IDE integration for tutor compilation yet.
+* Pitfalls: the first time it can take some effort to collect all the relevant information on license, authors, funding, citation, etc.