Track-specific documentation (#93)

* Docs WIP

* Update docs/TESTS.md

* Partial rewrite

* Update docs

* Add shared docs

---------

Co-authored-by: Erik Schierboom <[email protected]>

docs/INSTALLATION.md

@@ -1,15 +1,27 @@
 # Installation
 
-<!-- TODO: write document
+Arturo comes with pre-built binaries for Linux, MacOS, and Windows in both `full` and `mini` build flavors.
+For this track, we'll be using [the nightly `full` build release of Arturo][nightly] which includes the entire standard library and mostly notably package manager support.
+This full build is only supported for `x86_64` Linux and Windows platforms.
 
-  This document should describe what the student needs to install
-  to allow working on the track on their local system using the CLI.
+## Downloading Nightly
 
-  You can include the installation instructions in this document, but
-  usually it is better to link to a resource with the official installation
-  instructions, to prevent the instructions from becoming outdated.
+On the [nightly Arturo build page][nightly], find the latest `full` release for your current platform (Linux or Windows only).
+The page lists the pre-built releases as `arturo_0.9.83-<year>-<month>-<date>-<platform>-full`.
+For example, the latest `full` build for Linux as of this writing is `arturo_0.9.83-2024-06-12-linux-full`.
+Download the correct release for your platform and extract the `arturo` binary from the archive.
+Move that binary to a directory on your system's PATH environment variable.
+Common locatons might be `/usr/local/bin` or `~/.local/bin` on Linux or perhaps `C:\arturo` on Windows.
+You can verify the binary is on your PATH by running `arturo --version` at the command-line.
+That should print something like `arturo v/0.9.83 b/3112 (amd64/linux)`, and the specific version and platform identifiers may be different for you.
 
-  The contents of this document are displayed on the track's documentation
-  page at `https://exercism.org/docs/tracks/<track>/installation`.
+## Running Arturo code
+At that point, you're reaady to start writing Arturo code!
+To access the Arturo REPL interactive console, run `arturo` at the command-line.
+To execute an Arturo script, run `arturo <file>` at the command-line inside.
+To import packages, run `import "<package-name>"!` inside the REPL.
+If the package is not already installed, Arturo will download and install the package for you.
+You can find packages using [Packager, the official Arturo package registry][packager].
 
-  See https://exercism.org/docs/building/tracks/docs for more information. -->
+[nightly]: https://github.com/arturo-lang/nightly/releases
+[packager]: https://pkgr.art/

docs/LEARNING.md

@@ -1,13 +1,7 @@
 # Learning
 
-<!-- TODO: write document
+* [Arturo In A Nutshell][nutshell] is a concise "Learn X in Y Minutes"-style overview of basic Arturo syntax and features
+* [Rosetta Code][rosetta-code] has over 770+ Arturo code examples for many different tasks.
 
-  This document should link to learning resources.
-
-  Feel free to link to any good learning resources you know, whether they
-  be websites, blogs, books, videos or courses.
-
-  The contents of this document are displayed on the track's documentation
-  page at `https://exercism.org/docs/tracks/<track>/learning`.
-
-  See https://exercism.org/docs/building/tracks/docs for more information. -->
+[nutshell]: https://arturo-lang.io/master/documentation/in-a-nutshell/
+[rosetta-code]: https://rosettacode.org/wiki/Category:Arturo

docs/RESOURCES.md

@@ -1,13 +1,11 @@
 # Resources
 
-<!-- TODO: write document
-
-  This document should link to useful resources.
-
-  Feel free to link to any good resources you know, whether they
-  be websites, videos, mailing lists, etc.
-
-  The contents of this document are displayed on the track's documentation
-  page at `https://exercism.org/docs/tracks/<track>/resources`.
-
-  See https://exercism.org/docs/building/tracks/docs for more information. -->
+* [Official Documentation][official-docs] covers syntax, language features, and the standard library modules.
+* [Arturo Discord][discord] is Arturo's official Discord server.
+* [Rosetta Code][rosetta-code] has over 770+ Arturo code examples for many different tasks.
+* [Packager][packager] is Arturo's official package registry.
+
+[official-docs]: https://arturo-lang.io/master/documentation/
+[discord]: https://discord.gg/YdVK2CB
+[packager]: https://pkgr.art/
+[rosetta-code]: https://rosettacode.org/wiki/Category:Arturo

docs/TESTS.md

@@ -1,15 +1,250 @@
 # Tests
 
-<!-- TODO: write document
+This track uses the [Unitt unit-testing package][unitt].
+If not already installed, Arturo will download this package automatically at runtime.
 
-  This document should describe everything related to running tests in the track.
+To run tests, navigate to the exercise folder in your terminal and run either `arturo tester.art` or `exercism test`.
 
-  If your track uses skipped tests, this document can explain why thet is used and
-  how to unskip tests.
+Each exercse folder contains three key files:
+    `src/<exercise-name>.art` contains the solution to be tested.
+    `tests/test-<exercise-name>.art` contains the exercise tests 
+    `tester.art` is the testing entry-point which runs and reports the tests inside `tests/test-<exercise-name>.art`.
 
-  This document can also link to the testing framework documentation.
 
-  The contents of this document are displayed on the track's documentation
-  page at `https://exercism.org/docs/tracks/<track>/tests`.
+## Test Structure
 
-  See https://exercism.org/docs/building/tracks/docs for more information. -->
+
+`tests/test-<exercise-name>.art` contains the test cases for the exercise.
+These tests are organized into one or more test suites.
+Each test suite is defined with the `suite` word and contains one or more test cases defined with the `test` word.
+After the first test case, all test cases are initially skipped with the `skip` attribute.
+Replace `test.skip` with `test`, removing the `skip` attribute, for the test case you want to unskip.
+
+Withn each test case, there will be a descriptive message which is reported when the test case is run.
+There will also be one or more assertions comparing an expected value (on the left) to a value returned by your code (on the right).
+
+For example, the following code is a reduced test suite for the Leap exercise.
+
+```arturo
+import {unitt}!
+import {src/leap}!
+
+suite "Leap" [
+    test "a year not divisible by 4 is a common year" [
+        result: isLeap? 2015
+        assert -> false = result
+    ]
+
+    test.skip "a year divisible by 2 and not divisible by 4 is a common year" [
+        result: isLeap? 1970
+        assert -> false = result
+    ]
+
+    test.skip "a year divisible by 4 and not divisible by 100 is a leap year" [
+        result: isLeap? 1996
+        assert -> true = result
+    ]
+]
+```
+
+After both `unitt` and your Leap solution is imported, Arturo evaluates the "Leap" suite, encountering three tests.
+Each test has a description and a message, but only the first one will be run.
+
+## Test Output
+
+Looking at the Leap exercise, let's see what the output of running the test suite is.
+Let's use the following solution as a starting point.
+
+```arturo
+isLeap?: function [year][
+    panic "please implement the isLeap? function"
+]
+```
+
+If we run the tests now, Arturo will panic while evaluating the first test.
+Since it was unsuccessful in evaluating the first test, it will not continue to evaluate the other tests.
+It will also report 0 assertions encountered due to this issue, looking something like this:
+
+```plaintext
+===== tests\test-leap.art =====
+
+Suite: Leap 
+
+
+══╡ Program Error ╞═════════════════════════════════════════════════ <script> ══
+
+  please implement the isLeap? function
+
+
+
+===== Statistics =====
+
+⏏️    TOTAL: 0 assertions
+✅  PASSED: 0 assertions
+⏩ SKIPPED: 0 assertions
+❌  FAILED: 0 assertions
+
+===== ========== =====
+```
+
+
+At this point, we need to remove the panic and replace it with some code that will pass the first test.
+
+
+```arturo
+isLeap?: function [year][
+    false
+]
+```
+
+If we rerun the tests, we will see output (below) that the first test passes, but the other two tests are skipped.
+The test description and assertions are reported with a leading emoji denoting a passed test (✅), a failed test (❌), or a skipped test (⏩).
+Under the statistics section, the total number of passing or failed assertions is reported, followed by the number of passed assertions, the number of skipped assertions, and finally the number of failed assertions.
+
+```plaintext
+===== tests\test-leap.art =====
+
+Suite: Leap
+
+    ✅ - assert that a year not divisible by 4 is a common year
+         assertion: false = false
+
+    ⏩ - assert that a year divisible by 2 and not divisible by 4 is a common year 
+         skipped!
+
+    ⏩ - assert that a year divisible by 4 and not divisible by 100 is a leap year
+         skipped!
+
+===== Statistics =====
+
+⏏️    TOTAL: 1 assertions
+✅  PASSED: 1 assertions
+⏩ SKIPPED: 2 assertions
+❌  FAILED: 0 assertions
+
+===== ========== =====
+```
+
+
+Unskipping the second test, we'll have the following tests:
+
+```arturo
+import {unitt}!
+import {src/leap}!
+
+suite "Leap" [
+    test "a year not divisible by 4 is a common year" [
+        result: isLeap? 2015
+        assert -> false = result
+    ]
+
+    test "a year divisible by 2 and not divisible by 4 is a common year" [
+        result: isLeap? 1970
+        assert -> false = result
+    ]
+
+    test.skip "a year divisible by 4 and not divisible by 100 is a leap year" [
+        result: isLeap? 1996
+        assert -> true = result
+    ]
+]
+```
+
+
+If we rerun the tests again, the second test passes, but the third test is still skipped.
+
+
+```plaintext
+===== tests\test-leap.art =====
+
+Suite: Leap
+
+    ✅ - assert that a year not divisible by 4 is a common year
+         assertion: false = false
+
+    ✅ - assert that a year divisible by 2 and not divisible by 4 is a common year 
+         assertion: false = false
+
+    ⏩ - assert that a year divisible by 4 and not divisible by 100 is a leap year
+         skipped!
+
+===== Statistics =====
+
+⏏️    TOTAL: 2 assertions
+✅  PASSED: 2 assertions
+⏩ SKIPPED: 1 assertions
+❌  FAILED: 0 assertions
+
+===== ========== =====
+```
+
+
+Let's unskip the third test and run the tests again.
+At this point, we'll encounter a failing test because the third test expects `true`, not `false`.
+
+
+```plaintext
+===== tests/test-leap.art =====
+
+Suite: Leap 
+ 
+    ✅ - assert that a year not divisible by 4 is a common year 
+         assertion: false = false
+
+    ✅ - assert that a year divisible by 2 and not divisible by 4 is a common year 
+         assertion: false = false
+
+    ❌ - assert that a year divisible by 4 and not divisible by 100 is a leap year 
+         assertion: true = false
+
+
+
+
+===== Statistics =====
+
+⏏️    TOTAL: 3 assertions
+✅  PASSED: 2 assertions
+⏩ SKIPPED: 0 assertions
+❌  FAILED: 1 assertions
+
+===== ========== =====
+
+
+══╡ Program Error ╞══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════ <script> ══
+
+  Some tests failed!
+```
+
+At this point, we need to fix the code to pass the third test. Once that's done, we can rerun the tests and see that all tests pass.
+
+```plaintext
+===== tests/test-leap.art =====
+
+Suite: Leap 
+ 
+    ✅ - assert that a year not divisible by 4 is a common year 
+         assertion: false = false
+
+    ✅ - assert that a year divisible by 2 and not divisible by 4 is a common year 
+         assertion: false = false
+
+    ✅ - assert that a year divisible by 4 and not divisible by 100 is a leap year 
+         assertion: false = false
+
+
+
+
+===== Statistics =====
+
+⏏️    TOTAL: 3 assertions
+✅  PASSED: 3 assertions
+⏩ SKIPPED: 0 assertions
+❌  FAILED: 0 assertions
+
+===== ========== =====
+```
+
+At this point, your solution can be submitted using `exercism submit` and the online test runner will test your code.
+The online test runner unskips and runs all the tests every time so make sure you're not skipping any tests before submitting.
+
+[unitt]: [https://unitt.pkgr.art/]

exercises/shared/.docs/help.md

@@ -1,21 +1,11 @@
 # Help
 
-<!-- TODO: write document
+Here are some resources for getting help if you run into trouble
 
-  This document should contain track-specific instructions on how to get help when
-  the student is stuck.
+* [Official Documentation][official-docs] covers syntax, language features, and the standard library modules.
+* [Arturo Discord][discord] is Arturo's official Discord server.
+* [Rosetta Code][rosetta-code] has over 770+ Arturo code examples for many different tasks.
 
-  The instructions should be short and to the point.
-
-  You could link to resources like Gitter channels, forums or mailing lists:
-  whatever can help a student become unstuck.
-
-  This document should **not** link to Exercism-wide (track-agnostic) help resources,
-  as those resources will automatically be included in the HELP.md file.
-
-  The links in this document can overlap with those in docs/LEARNING.md or docs/RESOURCES.md
-
-  When a student downloads an exercise via the CLI, this file's contents are
-  included into the HELP.md file.
-
-  See https://exercism.org/docs/building/tracks/shared-files for more information. -->
+[official-docs]: https://arturo-lang.io/master/documentation/
+[discord]: https://discord.gg/YdVK2CB
+[rosetta-code]: https://rosettacode.org/wiki/Category:Arturo