docs: document latest API changes

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

docs/api_changes.md

@@ -0,0 +1,90 @@
+This document keeps a record of all changes to Moonraker's remote
+facing APIs.
+
+### August 16 2020
+- The structure of data returned from `/printer/info` (`get_printer_info`)
+  has changed to the following format:
+  ```json
+  {
+      state: "<klippy state>",
+      state_message: "<current state message>",
+      hostname: "<hostname>",
+      software_version: "<version>",
+      cpu_info: "<cpu_info>",
+      klipper_path: "<moonraker use only>",
+      python_path: "<moonraker use only>",
+      log_file: "<moonraker use only>",
+      config_file: "<moonraker use only>",
+  }
+  ```
+  The "state" item can be one of the following:
+  - "startup" - Klippy is in the process of starting up
+  - "ready" - Klippy is ready
+  - "shutdown" - Klippy has shutdown
+  - "error" - Klippy has experienced an error during startup
+
+  The message from each state can be found in the `state_message`.
+- A `webhooks` printer object has been added, available for subscription or
+  query. It includes the following items:
+  - `state` - Printer state identical to that returned from `/printer/info`
+  - `state_message` - identical to that returned from  `/printer/info`
+- `/printer/objects/status` (`get_printer_objects_status`) has been renamed to
+  `/printer/objects/query` (`get_printer_objects_query`).  The format of the
+  websocket request has changed, it should now look like the following:
+  ```json
+  {
+      jsonrpc: "2.0",
+      method: "get_printer_objects_query",
+      params: {
+          objects: {
+            gcode: null,
+            toolhead: ["position", "status"]
+          }
+      },
+      id: <request id>
+  }
+  ```
+  As shown above, printer objects are now wrapped in an "objects" parameter.
+  When a client wishes to subscribe to all items of a printer object, they
+  should now be set to `null` rather than an empty array.
+  The return value has also changed:
+  ```json
+  {
+    eventtime: <klippy time of update>,
+    status: {
+      gcode: {
+        busy: true,
+        gcode_position: [0, 0, 0 ,0],
+        ...},
+      toolhead: {
+        position: [0, 0, 0, 0],
+        status: "Ready",
+        ...},
+      ...}
+    }
+  ```
+  The `status` item now contains the requested status.
+- `/printer/objects/subscription` (`post_printer_objects_subscription`) is now
+  `printer/objects/subscribe` (`post_printer_objects_subscribe`).  This
+  request takes parameters in the same format as the `query`.  It now returns
+  state for all currently subscribed objects (in the same format as a `query`).
+  This data can be used to initialize all local state after the request
+  completes.
+- Subscriptions are now pushed as "diffs".  Clients will only recieve updates
+  for subscribed items when that data changes.  This requires that clients
+  initialize their local state with the data returned from the subscription
+  request.
+- The structure of data returned from `/printer/objects/list` has changed.  It
+  now returns an array of available printer objects:
+  ```json
+  { objects: ["gcode", "toolhead", "bed_mesh", "configfile",....]}
+  ```
+- The `notify_klippy_state_changed` notification has been removed.  Clients
+  can subscribe to `webhooks` and use `webhooks.state` to be notified of
+  transitions to the "ready" and "shutdown" states
+- A `notify_klippy_disconnected` event has been added to notify clients
+  when the connection between Klippy and Moonraker has been terminated.
+  This event is sent with no parameters:
+  ```json
+  {jsonrpc: "2.0", method: "notify_klippy_disconnected"}
+  ```

docs/installation.md

@@ -10,6 +10,37 @@ Klipper should be installed prior to installing Moonraker.  Please see
 [Klipper's Documention](https://github.com/KevinOConnor/klipper/blob/master/docs/Installation.md)
 for instructions on how to do this.
 
+After Klipper is installed, you need to modify its "default" file.  This file
+contains klipper's command line arguments, and you must add an argument that
+instructs Klippy to create a Unix Domain socket:
+```
+sudo nano /etc/default/klipper
+```
+You should see a file that looks something like the following:
+```
+# Configuration for /etc/init.d/klipper
+
+KLIPPY_USER=pi
+
+KLIPPY_EXEC=/home/pi/klippy-env/bin/python
+
+KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log"
+```
+
+You need to add `-a /tmp/klippy_uds` to KLIPPY_ARGS:
+```
+# Configuration for /etc/init.d/klipper
+
+KLIPPY_USER=pi
+
+KLIPPY_EXEC=/home/pi/klippy-env/bin/python
+
+KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds"
+```
+You may also want to take this opportunity to change the location of
+printer.cfg if you enable Moonraker's "config_path" option (see the
+[configuration section](#moonraker-configuration-moonrakerconf) for more information).
+
 You can now install the Moonraker application:
 ```
 cd ~

docs/web_api.md

@@ -100,7 +100,7 @@ that uses promises to return responses and errors (see json-rcp.js).
   or subscription.  This list will be passed in an "objects" parameter.
 
   ```json
-  { objects: [gcode, toolhead, bed_mesh, configfile...]}
+  { objects: ["gcode", "toolhead", "bed_mesh", "configfile",....]}
   ```
 
 ### Query the a status for an object, or group of objects:
@@ -671,11 +671,16 @@ Printer generated events are sent over the websocket as JSON-RPC 2.0
 notifications.  These notifications are sent to all connected clients
 in the following format:
 
-`{jsonrpc: "2.0", method: <event method name>, params: [<event state>]}`
+`{jsonrpc: "2.0", method: <event method name>}`
 
-It is important to keep in mind that the `params` value will always be
+OR
+
+`{jsonrpc: "2.0", method: <event method name>, params: [<event parameter>]}`
+
+If a notification has parameters,  the `params` value will always be
 wrapped in an array as directed by the JSON-RPC standard.  Currently
-all notifications available are broadcast with a single parameter.
+all notifications available are broadcast with either no parameters
+or a single parameter.
 
 ### Gcode response:
 All calls to gcode.respond() are forwarded over the websocket.  They arrive
@@ -689,21 +694,12 @@ Status Subscriptions arrive as a "notify_status_update" notification:
 `{jsonrpc: "2.0", method: "notify_status_update", params: [<status_data>]}`
 
 The structure of the status data is identical to the structure that is
-returned from a status request.
+returned from an object query's "status" attribute.
 
-### Klippy Process State Changed:
-The following Klippy state changes are broadcast over the websocket:
-- ready
-- disconnect
-- shutdown
+### Klippy Disconnected:
+Notify clients when Moonraker's connection to Klippy has terminated
 
-Note that Klippy's "ready" is different from the Printer's "ready".  The
-Klippy "ready" state is broadcast upon startup after initialization is
-complete.  It should also be noted that the websocket will be disconnected
-after the "disconnect" state, as that notification is broadcast prior to a
-restart. Klippy State notifications are broadcast in the following format:
-
-`{jsonrpc: "2.0", method: "notify_klippy_state_changed", params: [<state>]}`
+`{jsonrpc: "2.0", method: "notify_klippy_disconnected"}`
 
 ### File List Changed
 When a client makes a change to the virtual sdcard file list