docs: Add an Application Library chapter

Signed-off-by: Daniel Thompson <daniel@redfelineninja.org.uk>

6 files changed, 80 insertions, 24 deletions

diff --git a/docs/apps.rst b/docs/apps.rst
new file mode 100644
index 0000000..7b24401
--- /dev/null
+++ b/docs/apps.rst
@@ -0,0 +1,39 @@
+.. _Application Library:
+
+Application Library
+===================
+
+.. contents::
+    :local:
+
+Built-in
+--------
+
+The built-in application are summarised below but since these apps are
+considers to be examples they are described in detail as part of the
+:ref:`Wasp-os Reference Manual`: 
+
+ * :py:class:`.ClockApp`
+ * :py:class:`.FlashlightApp`
+ * :py:class:`.LauncherApp`
+ * :py:class:`.PagerApp`
+ * :py:class:`.TestApp`
+ * :py:class:`.TemplateApp``
+
+Watch faces
+-----------
+
+.. automodule:: apps.fibonacci_clock
+
+This is enabled by default in the simulator. The app is bundled in the
+firmware image but it is disabled by default to keep RAM available for
+user developed applications. It can be enabled by modifying ``main.py``.
+
+Games
+-----
+
+.. automodule:: apps.gameoflife
+
+This is enabled by default in the simulator. The app is bundled in the
+firmware image but it is disabled by default to keep RAM available for
+user developed applications. It can be enabled by modifying ``main.py``.
diff --git a/docs/index.rst b/docs/index.rst
index 8f38273..75c4bc1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,6 +12,7 @@ Welcome to WASP-OS's documentation!
 
    README
    install
+   apps
    appguide
    wasp
    contributing
diff --git a/docs/wasp.rst b/docs/wasp.rst
index 34a3d9e..6ec18ef 100644
--- a/docs/wasp.rst
+++ b/docs/wasp.rst
@@ -63,9 +63,6 @@ Applications
    :members:
    :undoc-members:
 
-.. automodule:: apps.fibonacci_clock
-   :members:
-
 .. automodule:: apps.flashlight
    :members:
    :undoc-members:
diff --git a/wasp/apps/fibonacci_clock.py b/wasp/apps/fibonacci_clock.py
index 3718cfc..0f9ebfd 100644
--- a/wasp/apps/fibonacci_clock.py
+++ b/wasp/apps/fibonacci_clock.py
@@ -9,6 +9,11 @@ mathematician Fibonacci in the 13th century. This is a sequence starting with
 1 and 1, where each subsequent number is the sum of the previous two. For the
 clock I used the first 5 terms: 1, 1, 2, 3 and 5.
 
+    .. figure:: res/FiboApp.png
+        :width: 179
+
+        Screenshot of the fibonacci clock application
+
 The screen of the clock is made up of five squares whose side lengths match
 the first five Fibonacci numbers: 1, 1, 2, 3 and 5. The hours are displayed
 using red and the minutes using green. When a square is used to display both
@@ -51,12 +56,7 @@ icon = (
 )
 
 class FibonacciClockApp():
-    """Displays the time as a Fibonacci Clock
-
-    .. figure:: res/FiboApp.png
-        :width: 179
-
-        Screenshot of the fibonacci clock application
+    """Displays the time as a Fibonacci Clock.
     """
     NAME = 'Fibo'
     ICON = icon
diff --git a/wasp/apps/gameoflife.py b/wasp/apps/gameoflife.py
index f1f1dbe..109888c 100644
--- a/wasp/apps/gameoflife.py
+++ b/wasp/apps/gameoflife.py
@@ -1,6 +1,28 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 # Copyright (C) 2020 Daniel Thompson
-"""Conway's Game of Life.
+"""Conway's Game of Life
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Game of Life is a "no player game" played on a two dimensional grid
+where the rules interact to make interesting patterns.
+
+    .. figure:: res/LifeApp.png
+        :width: 179
+
+        Screenshot of the Game of Life application
+
+The game is based on four simple rules:
+
+    1. Death by isolation: a cell dies if has fewer than two live neighbours.
+
+    2. Death by overcrowding: a cell dies if it has more than three live
+       neighbours.
+
+    3. Survival: a living cell continues to survive if it has two or three
+       neighbours.
+
+    4. Reproduction: a dead cell comes alive if it has exactly three
+       neighbours.
 
 On 11 April 2020 John H. Conway who, among many, many other
 achievements, devised the rule set for his Game of Life, died of
@@ -71,20 +93,10 @@ def set_cell(board, stride: int, x: int, y: int, v: bool):
 def game_of_life(b, xmax: int, ymax: int, nb):
     """Run a single generation of Conway's Game of Life
 
-    1. Death by isolation: a cell dies if has fewer than two live neighbours.
-
-    2. Death by overcrowding: a cell dies if it has more than three live
-       neighbours.
-
-    3. Survival: a living cell continues to survive if it has two or three
-       neighbours.
-
-    4. Reproduction: a dead cell comes alive if it has exactly three
-       neighbours.
-
-    In the code below we have simplified the above rules to "a cell is
-    alive it has three live neighbours or if it was previously alive
-    and has two neighbours, otherwise it is dead.".
+    In the code below we have simplified the rules described at the top
+    of this file to "a cell is alive it has three live neighbours or if
+    it was previously alive and has two neighbours, otherwise it is
+    dead.".
     """
     board = ptr32(b)
     next_board = ptr32(nb)
diff --git a/wasp/boards/simulator/main.py b/wasp/boards/simulator/main.py
index 88fb87e..4310677 100644
--- a/wasp/boards/simulator/main.py
+++ b/wasp/boards/simulator/main.py
@@ -2,4 +2,11 @@
 # Copyright (C) 2020 Daniel Thompson
 
 import wasp
+
+from apps.fibonacci_clock import FibonacciClockApp
+wasp.system.register(FibonacciClockApp())
+
+from apps.gameoflife import GameOfLifeApp
+wasp.system.register(GameOfLifeApp())
+
 wasp.system.run()