remove summary from mothballs, more API docs

CHANGELOG.md

@@ -5,9 +5,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [v4.1.0-pre] - Unreleased
+### Fixed
+- Clear Debug.summary field when making mothballs
+
 ### Added
 - More log events
 - [Log channels document](docs/logs.md)
+- More detailed [API documntation](docs/api.md)
 
 ## [v4.0.0] - 2020-10-14
 ### Fixed

docs/api.md

@@ -27,7 +27,7 @@ Returns the current MOTH event state as a JSON object.
 ```json
 {
     "Config": {
-        "Devel": true/false
+        "Devel": false # true means this is a development server
     },
     "Messages: "HTML to be rendered as broadcast messages",
     "TeamNames": {
@@ -47,6 +47,51 @@ Returns the current MOTH event state as a JSON object.
 }
 ```
 
+#### Example HTTP transaction
+
+##### Request
+
+```
+GET /state HTTP/1.0
+
+```
+
+##### Response
+
+This response has been reflowed for readability:
+an actual on-wire response would not have newlines or indentation.
+
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+
+{"Config":
+  {"Devel":false},
+  "Messages":"<p>Welcome to the event!</p><p>Event ends at 19:00!</p>",
+  "TeamNames":{
+      "0":"Mike and Jack",
+      "12":"Team 2",
+      "4":"Team 8"
+    },
+    "PointsLog":[
+        [1602702696,"0","nocode",1],
+        [1602702705,"0","sequence",1],
+        [1602702787,"0","nocode",2],
+        [1602702831,"0","sequence",2],
+        [1602702839,"4","nocode",3],
+        [1602702896,"0","sequence",8],
+        [1602702900,"4","nocode",4],
+        [1602702913,"0","sequence",16]
+    ],
+    "Puzzles":{
+        "indy":[12],
+        "nocode":[1,2,3,4,10],
+        "sequence":[1,2,8,16,19],
+        "steg":[1]
+    }
+}
+```
+
 ### `/register`
 
 Registers a name to a team ID.
@@ -75,6 +120,29 @@ An object inspired by [JSend](https://github.com/omniti-labs/jsend):
 }
 ```
 
+#### Example HTTP transaction
+
+##### Request
+
+```
+POST /register HTTP/1.0
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 26
+
+id=b387ca98&name=dirtbags
+```
+
+##### Repsonse
+
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+Content-Length=86
+
+{"status":"success","data":{"short":"registered","description":"Team ID registered"}}
+```
+
+
 ### `/answer`
 
 Submits an answer for points.
@@ -100,6 +168,29 @@ An object inspired by [JSend](https://github.com/omniti-labs/jsend):
 }
 ```
 
+#### Example HTTP transaction
+
+##### Request
+
+```
+POST /answer HTTP/1.0
+Content-Type: application/x-www-form-urlencoded
+Content-Length: 62
+
+id=b387ca98&category=sequence&points=2&answer=achilles+turnip
+```
+
+##### Repsonse
+
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+Content-Length=83
+
+{"status":"fail","data":{"short":"not accepted","description":"Incorrect answer"}}
+```
+
+
 ### `/content/{category}/{points}/{filename}`
 
 Retrieves static content associated with a puzzle.
@@ -122,3 +213,60 @@ so `curl` and `wget` can be used.
 Raw file octets,
 with a (hopefully) suitable
 `Content-type` HTTP header field.
+
+#### Example HTTP transaction
+
+##### Request
+
+```
+GET /content/sequence/1/puzzle.json HTTP/1.0
+
+```
+
+##### Repsonse
+
+```
+HTTP/1.0 200 OK
+Content-Type: application/json
+Content-Length: 397
+
+{"Pre":{"Authors":["neale"],"Attachments":[],"Scripts":[],"Body":"\u003cp\u003e1 2 3 4 5 ⬜\u003c/p\u003e\n","AnswerPattern":"","AnswerHashes":["e7f6c011776e8db7cd330b54174fd76f7d0216b612387a5ffcfb81e6f0919683"]},"Post":{"Objective":"","Success":{"Acceptable":"","Mastery":""},"KSAs":null},"Debug":{"Log":[],"Errors":[],"Hints":[],"Summary":"Simple introduction to how this works"},"Answers":[]}
+```
+
+
+`puzzle.json`
+-------
+
+The special file `puzzle.json` describes a puzzle. It is a JSON object with the following fields:
+
+```json
+{
+  "Pre": { # Things which appear before the puzzle is solved
+    "Authors": ["Neale Pickett"], # List of puzzle authors, usually rendered as a footnote
+    "Attachments": ["tiger.jpg"],  # List of files attached to the puzzle
+    "Scripts": [],  # List of scripts which should be included in the HTML render of the puzzle
+    "Body": "<p>Can you find the hidden text?</p><p><img src=\"tiger.jpg\" alt=\"Grr\" /></p>\n", # HTML puzzle body
+    "AnswerPattern": "", # Regular expression to include in HTML input tag for validation
+    "AnswerHashes": [ # List of SHA265 hashes of correct answers, for client-side answer checking
+      "f91b1fe875cdf9e969e5bccd3e259adec5a987dcafcbc9ca8da62e341a7f29c6"
+    ]
+  },
+  "Post": { # Things reveal after the puzzle is solved
+    "Objective": "Learn to examine images for hidden text", # Learning objective
+    "Success": { # Measures of learning success
+      "Acceptable": "Visually examine image to find hidden text",
+      "Mastery": "Visually examine image to find hidden text"
+    },
+    "KSAs": null # Knowledge, Skills, and Abilities covered by this puzzle
+  },
+  "Debug": { # Debugging output used in development: all fields are emptied when making mothballs
+    "Log": [], # Debug message log
+    "Errors": [], # Errors encountered generating this puzzzle
+    "Hints": [ # Hints for instructional assistants to provide to participants
+        "Zoom in to the image and examine all sections carefully"
+    ], 
+    "Summary": "text in image" # Summary of this puzzle, to help identify it in an overview of puzzles
+  },
+  "Answers": ["sandwich"] # List of answers: empty in production
+}
+```

pkg/transpile/mothball.go

@@ -44,6 +44,7 @@ func Mothball(c Category, w io.Writer) error {
 		puzzle.Debug.Errors = []string{}
 		puzzle.Debug.Hints = []string{}
 		puzzle.Debug.Log = []string{}
+		puzzle.Debug.Summary = ""
 
 		// Write out Puzzle object
 		penc := json.NewEncoder(pw)