Update documentation

baygon/__main__.py

@@ -171,31 +171,34 @@ def _traverse_group(self, tests):
                 self.points_total += test.points
                 if issues is None:  # Skipped
                     click.secho(" SKIPPED", fg="yellow")
-                    click.secho(
-                        "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
-                        fg="blue",
-                        dim=True,
-                    )
+                    if self.ran_commands:
+                        click.secho(
+                            "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
+                            fg="blue",
+                            dim=True,
+                        )
                     self.skipped += 1
                     continue
                 display_pad(self.align_column - test_name_length(test))
                 if not issues:
                     self.successes += 1
                     click.secho(" PASSED", fg="green")
-                    click.secho(
-                        "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
-                        fg="blue",
-                        dim=True,
-                    )
+                    if self.ran_commands:
+                        click.secho(
+                            "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
+                            fg="blue",
+                            dim=True,
+                        )
                     self.points_earned += test.points
                 else:
                     self.failures += 1
                     click.secho(" FAILED", fg="red", bold=True)
-                    click.secho(
-                        "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
-                        fg="blue",
-                        dim=True,
-                    )
+                    if self.ran_commands:
+                        click.secho(
+                            "".join([f"  $ {cmd}\n" for cmd in self.ran_commands]),
+                            fg="blue",
+                            dim=True,
+                        )
                     for issue in issues:
                         click.secho(
                             "  " * len(test.id) + "- " + str(issue), fg="magenta"

baygon/score.py

@@ -2,7 +2,7 @@
   Used in academic.
 """
 
-from decimal import Decimal, getcontext, ROUND_HALF_UP
+from decimal import Decimal, getcontext, ROUND_HALF_UP, ROUND_DOWN
 
 
 def float_or_int(value):

docs/docs/.vuepress/config.ts

@@ -26,6 +26,7 @@ export default defineUserConfig({
           { text: 'Getting Started', link: '/guide/' },
           { text: 'Syntax', link: '/guide/syntax.md' },
           { text: 'Scripting', link: '/guide/scripting.md' },
+          { text: 'Academic Use', link: '/guide/score.md' },
           { text: 'Advanced', link: '/guide/advanced.md' },
         ],
       },

docs/docs/guide/README.md

@@ -1,9 +1,13 @@
-# Introduction
+# What is Baygon?
 
-Baygon is a minimalistic test framework for any types of executables. It provides a simple way of testing code with a [JSON](https://en.wikipedia.org/wiki/JSON) or a [YAML](https://en.wikipedia.org/wiki/YAML) description of tests.
+**Baygon** is a minimalistic test framework for any types of executables. It provides a simple way of testing code with a [JSON](https://en.wikipedia.org/wiki/JSON) or a [YAML](https://en.wikipedia.org/wiki/YAML) description of tests.
+
+It is mainly designed for simple tests in academic environments, but it can be used for any kind of tests.
+
+Points can be assigned to tests, group of tests or automatically distributed based on the number of tests. The total earned points can be used to calculate the final assignment grade.
 
 ::: warning
-Baygon v1 is currently in `beta` stage. It's ready to be used for building functional tests, but the config and API are not stable enough, which is likely to have breaking changes between minor releases.
+Baygon is currently in `beta` stage. It's ready to be used for building functional tests, but the config and API are not stable enough, which is likely to have breaking changes between minor releases.
 :::
 
 ## How it works
@@ -14,6 +18,10 @@ Based on the description file, a `TestSuite` is built. A `TestSuite` is a collec
 
 By default Baygon will run all the tests in the description file.
 
+## What a strange name!
+
+Baygon is a brand of insecticide popularized in the 80s by the commercial ads featuring Michel Leeb. The name was chosen because it's a simple and short name that is easy to remember. And Baygon is meant to kill bugs in your code!
+
 ## Get started
 
 Let's say you have a C program you want to test:

docs/docs/guide/score.md

@@ -0,0 +1,74 @@
+# Academic Assignment
+
+Baygon is well designed to handle academic assignments. You can specify the points for each test, group of tests or at the top level.
+
+The configuration keys you can use are:
+
+**`points`**
+
+The total points that can be earned from the whole suite, group of tests or test.
+
+**`weight`**
+
+The weight of a test or group of tests. The weight is used to calculate the available points. A default `weight` value of `10` is used but you can set it to any value you want according to your needs.
+
+**`min-points`**
+
+When using weights, for instance if you have a group of test awarded 2 points shared in three tests of equally weights, each test will be awarded 0.666...points. The `min-points` key allows you to set a minimum value for the points. In this case, if you set `min-points` to `1`, each test will be awarded 1 point. Typical values are `1`, `0.5`, `0.25` or `0.1`.
+
+Baygon will automatically figure out how to assign points to each test based on your entries. Some rules apply:
+
+1. Without any other information each successfull test is awarded 1 points.
+2. If a total number of points is specified at any level, the points are distributed equally among the subtests.
+3. Weights can be used influence the distribution of points. The default weight is 10.
+
+To give you some examples we will simplify the configuration files.
+
+## Equally distributed points
+
+By default we know that `min-points` is 0.1 and with equal `weight` on each test, the points are distributed equally.
+
+```yaml
+version: 1
+points: 10
+tests:
+  - name: Test 1 # 3.4
+  - name: Test 2 # 3.3
+  - name: Test 3 # 3.3
+```
+
+## Weighted points distribution
+
+This time we have two subgroups of tests. The first group has a weight of 5 and the second group has a weight of 10. The total points are 10.
+
+```yaml
+version: 1
+points: 12
+tests:
+  - name: Group 1 # 4
+    weight: 5
+    tests:
+      - name: Test 1 # 2
+      - name: Test 2 # 2
+  - name: Group 2 # 8
+    weight: 10
+    tests:
+      - name: Test 3 # 4
+      - name: Test 4 # 4
+```
+
+## Using the result
+
+The number of points is given on the output it has the form of:
+
+```text
+Points: 4/10
+```
+
+Alternatively you may want to use the report feature to generate a report in JSON or YAML format. The report will contain the points for each test and group of tests.
+
+```console
+baygon --report=report.json
+```
+
+This report could be used by a grading system to automatically assign grades to students.

docs/docs/guide/syntax.md

@@ -205,22 +205,3 @@ tests:
         - regex: f(oo|aa|uu) # Must match
         - equals: foobar
 ```
-
-## Given Points
-
-In the case Baygon is used in an academic context, you can assign points to each test. The following assigns 10 points to the first test and 5 to the second:
-
-```yaml
-version: 1
-tests:
-  - points: 10
-    args: [1, 2]
-    stdout: 3
-  - points: 5
-    args: [1, 2]
-    stdout: 3
-```
-
-Points can be given at different levels:
-
-1. At the top level, all tests will have the same points.