Add some images to the tutorial

Use them as functional tests for good measure.

docs/tutorial.md

@@ -65,7 +65,11 @@ We should start actually drawing something. Change the file to read:
 ```
 
 You should see the words "Hello world!" appear in white in the middle of the
-window. Lets unpick what is happening here: Each line beginning `!` and followed
+window.
+
+![Simple "Hello World!" image](tutorial_images/tutorial1.jpg)
+
+Lets unpick what is happening here: Each line beginning `!` and followed
 by a name creates a *node* of that *kind*. These can be followed by any number
 of *name*`=`*value* pairs, each of which adds an *attribute* to the preceding
 node. Values are *vectors* of any combination of numbers or Unicode strings
@@ -142,6 +146,9 @@ things to learn from this:
   value then the number represents a gray level from 0 to 1, if given as three
   values then the number represents an RGB triplet also in the range 0 to 1.
 
+!["Hello World!" written in white with a slight red
+shadow](tutorial_images/tutorial2.jpg)
+
 We can pull out some of the duplicated values in these two text nodes so that
 the intention is more clear. Try changing the code to the following (be careful
 of the new indentation):
@@ -192,6 +199,9 @@ the default drawing origin of the top left. In fact, if we had left off the
 drawing color is black. None of the drawing context introduced by the
 `!group` node is retained outside of it.
 
+!["Hello World!" written in white with a slight red shadow and "Figure 1" small
+in the top-left corner](tutorial_images/tutorial3.jpg)
+
 An important lesson to learn from this tiny example is that both block structure
 (this is *in* that) and context (like origin and paint color) are managed
 through indentation in **Flitter**. There are no braces or close tags, and no
@@ -343,6 +353,9 @@ evaluation of the loop body. The result of this loop is a 10-item vector of
 node so that the function returns a vector of 11 nodes. These 11 nodes are then
 appended to the group.
 
+!["Hello World!" written in white with a long red 3D shadow and "Figure 1" small
+in the top-left corner](tutorial_images/tutorial4.jpg)
+
 :::{note}
 **Flitter** is a *strict* functional programming language, and so ranges are
 fully evaluated before use. For this reason, ranges **must** include a stop
@@ -439,6 +452,9 @@ Names can be introduced with `let` in any expression sequence. The name will
 only be bound within that sequence (and only for expressions following the
 `let`). Therefore, outside of the loop the name `k` is not defined.
 
+!["Hello World!" written in white with a long rainbow 3D shadow and "Figure 1"
+small in the top-left corner](tutorial_images/tutorial5.jpg)
+
 ## Template Functions
 
 We are effectively using the `text3d()` function to define a new kind of

docs/tutorial_images/Makefile

@@ -0,0 +1,7 @@
+
+.PHONY: images
+
+images: tutorial1.jpg tutorial2.jpg tutorial3.jpg tutorial4.jpg tutorial5.jpg
+
+%.jpg: %.fl
+	flitter --offscreen --lockstep --fps=1 --runtime=1 $<

docs/tutorial_images/tutorial1.fl

@@ -0,0 +1,5 @@
+
+!window size=1920;1080
+    !record filename=(OUTPUT or 'tutorial1.jpg')
+        !canvas
+            !text text="Hello world!" font_size=100 point=960;540 color=1

docs/tutorial_images/tutorial2.fl

@@ -0,0 +1,7 @@
+
+!window size=1920;1080
+    !record filename=(OUTPUT or 'tutorial2.jpg')
+        !canvas
+            !group font_size=100 translate=960;540 color=1
+                !text text="Hello world!" point=-2;2 color=1;0;0
+                !text text="Hello world!"

docs/tutorial_images/tutorial3.fl

@@ -0,0 +1,8 @@
+
+!window size=1920;1080
+    !record filename=(OUTPUT or 'tutorial3.jpg')
+        !canvas
+            !group font_size=100 translate=960;540 color=1
+                !text text="Hello world!" point=-2;2 color=1;0;0
+                !text text="Hello world!"
+            !text text="Figure 1:" point=100;100 color=1

docs/tutorial_images/tutorial4.fl

@@ -0,0 +1,14 @@
+
+func text3d(text, offset, shadow_color)
+    for i in offset..0|-1
+        !text text=text point=-i;i color=shadow_color
+    !text text=text
+
+let SIZE=1920;1080
+
+!window size=SIZE
+    !record filename=(OUTPUT or 'tutorial4.jpg')
+        !canvas
+            !group font_size=100 translate=SIZE/2 color=1
+                text3d("Hello world!", 10, 1;0;0)
+            !text text="Figure 1:" point=100;100 color=1

docs/tutorial_images/tutorial5.fl

@@ -0,0 +1,15 @@
+
+func text3d(text, offset, start_hue)
+    for i in offset..0|-1
+        let k=i/offset
+        !text text=text point=-i;i color=hsv(start_hue-k;1;1-k)
+    !text text=text
+
+let SIZE=1920;1080
+
+!window size=SIZE
+    !record filename=(OUTPUT or 'tutorial5.jpg')
+        !canvas
+            !group font_size=100 translate=SIZE/2 color=1
+                text3d("Hello world!", 100, beat/10)
+            !text text="Figure 1:" point=100;100 color=1

tests/test_scripts.py

@@ -136,3 +136,29 @@ def test_diagrams(self):
                 finally:
                     if output_path.exists():
                         output_path.unlink()
+
+
+class TestDocumentationTutorial(unittest.TestCase):
+    """
+    Recreate the tutorial images and check them against the pre-calculated ones.
+    """
+
+    def test_diagrams(self):
+        scripts_dir = Path(__file__).parent.parent / 'docs/tutorial_images'
+        scripts = [path for path in scripts_dir.iterdir() if path.suffix == '.fl']
+        self.assertTrue(len(scripts) > 0)
+        for i, script in enumerate(scripts):
+            with self.subTest(script=script):
+                output_path = Path(tempfile.mktemp('.jpg'))
+                try:
+                    reference = PIL.Image.open(script.with_suffix('.jpg'))
+                    controller = EngineController(realtime=False, target_fps=1, run_time=1, offscreen=True,
+                                                  defined_names={'OUTPUT': str(output_path)})
+                    controller.load_page(script)
+                    asyncio.run(controller.run())
+                    output = PIL.Image.open(output_path)
+                    self.assertEqual(reference.size, output.size)
+                    self.assertLess(image_diff(reference, output), 0.002)
+                finally:
+                    if output_path.exists():
+                        output_path.unlink()