docs: update documenation with API and configuration changes

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

docs/configuration.md

@@ -5,10 +5,14 @@ references configuration for both Klipper (`printer.cfg`) and Moonraker
 configuration file is being refrenenced. A basic
 [sample configuration](./moonraker.conf) in the `docs` directory.
 
-## `[server]`
+## Core Components
 
-The `[server]` section provides essential configuration for Moonraker
+Moonraker's core components are always loaded regardless of configuration.
-and its core components.  This section is requrired.
+
+### `[server]`
+
+The `[server]` section provides essential configuration for Moonraker.
+This section is requrired.
 
 ```ini
 
@@ -38,6 +42,16 @@ max_upload_size: 1024
 enable_debug_logging: False
 #   When set to True Moonraker will log in verbose mode.  During this stage
 #   of development the default is False.
+```
+
+### `[file_manager]`
+
+The `file_manager` section provides configuration for Moonraker's file
+management functionality.  If omitted defaults will be used.
+
+```ini
+# moonraker.conf
+
 config_path:
 #   The path to a directory where configuration files are located. This
 #   directory may contain Klipper config files (printer.cfg) or Moonraker
@@ -45,18 +59,42 @@ config_path:
 #   files to this directory.  Note that this may not be the system root
 #   (ie: "/") and moonraker must have read and write access permissions
 #   for this directory.
+log_path:
+#   An optional path to a directory where log files are located.  Users may
+#   configure various applications to store logs here and Moonraker will serve
+#   them at "/server/files/logs/*".  The default is no log paths.
+queue_gcode_uploads: False
+#   When set to True the file manager will add uploads to the job_queue when
+#   the `start_print` flag has been set.  The default if False.
+```
+
+### `[database]`
+
+The `database` section provides configuration for Moonraker's lmdb database.
+If omitted defaults will be used.
+
+```ini
+moonraker.conf
+
 database_path: ~/.moonraker_database
 #   The path to the folder that stores Moonraker's lmdb database files.
 #   It is NOT recommended to place this file in a location that is served by
 #   Moonraker (such as the "config_path" or the location where gcode
 #   files are stored).  If the folder does not exist an attempt will be made
 #   to create it.  The default is ~/.moonraker_database.
-log_path:
-#   An optional path to a directory where log files are located.  Users may
-#   configure various applications to store logs here and Moonraker will serve
-#   them at "/server/files/logs/*".  The default is no log paths.
 enable_database_debug: False
 #   For developer use only.  End users should leave this option set to False.
+```
+### `[data_store]`
+
+The `data_store` section provides configuration for Moonraker's volatile
+data store.  Note that this is different from the `database`, as it stores
+data in memory and does not persist between restarts.  If omitted defaults
+will be used.
+
+```ini
+# moonraker.conf
+
 temperature_store_size: 1200
 #   The maximum number of temperature values to store for each sensor. Note
 #   that this value also applies to the "target", "power", and "fan_speed"
@@ -65,7 +103,35 @@ temperature_store_size: 1200
 gcode_store_size:  1000
 #   The maximum number "gcode lines" to store.  The default is 1000.
 ```
-## `[authorization]`
+
+### `[job_queue]`
+
+The `job_queue` section provides configuration for Moonraker's gcode job
+queuing.  If omitted defaults will be used.
+
+```ini
+# moonraker.conf
+
+load_on_startup: False
+#   When set to true the job queue will attempt to load the next
+#   pending job when Klipper reports as "Ready".  If the queue has
+#   been paused it will automatically resume.  Note that neither
+#   the job_transition_delay nor the job_transition_gcode are
+#   applied in this case.  The default is False.
+job_transition_delay:
+#   The amount of time to delay after completion of a job before
+#   loading the next job on the queue.  The default is no delay.
+job_transition_gcode:
+#   A gcode to execute after the completion of a job before the next
+#   job is loaded.  If a "job_transition_delay" has been configured
+#   this gcode will run after the delay.  The default is no gcode.
+```
+## Optional Components
+
+Optional Components are only loaded if present in `moonraker.conf`.  This
+includes components that may not have any configuration.
+
+### `[authorization]`
 
 The `[authorization]` section provides configuration for Moonraker's
 authorization module.
@@ -115,7 +181,7 @@ force_logins: False
 #   The default is False.
 ```
 
-## `[octoprint_compat]`
+### `[octoprint_compat]`
 Enables partial support of Octoprint API is implemented with the purpose of
 allowing uploading of sliced prints to a moonraker instance.
 Currently we support Slic3r derivatives and Cura with Cura-Octoprint.
@@ -126,7 +192,7 @@ Currently we support Slic3r derivatives and Cura with Cura-Octoprint.
 [octoprint_compat]
 ```
 
-## `[history]`
+### `[history]`
 Enables print history tracking.
 
 ```ini
@@ -135,7 +201,7 @@ Enables print history tracking.
 [history]
 ```
 
-## `[paneldue]`
+### `[paneldue]`
 Enables PanelDue display support.  The PanelDue should be connected to the
 host machine, either via the machine's UART GPIOs or through a USB-TTL
 converter.  Currently PanelDue Firmware Version 1.24 is supported.  Other
@@ -189,7 +255,7 @@ gcode:
                              duration=DURATION|float)}
 ```
 
-## `[power]`
+### `[power]`
 Enables device power control.  Currently GPIO (relays), RF transmitter, TPLink Smartplug,
 and Tasmota (via http) devices, HomeAssistant switch are supported.
 
@@ -205,14 +271,26 @@ off_when_shutdown: False
 #   If set to True the device will be powered off when Klipper enters
 #   the "shutdown" state.  This option applies to all device types.
 #   The default is False.
+on_when_upload_queued: False
+#   If set to True the device will power on if the file manager
+#   queues an upload while the device is off.  This allows for an automated
+#   "upload, power on, and print" approach directly from the slicer, see
+#   the configuration example below for details. The default is False.
 locked_while_printing: False
 #   If True, locks the device so that the power cannot be changed while the
 #   printer is printing. This is useful to avert an accidental shutdown to
 #   the printer's power.  The default is False.
 restart_klipper_when_powered: False
 #   If set to True, Moonraker will issue a "FIRMWARE_RESTART" to Klipper
-#   after the device has been powered on.  The default is False, thus no
+#   after the device has been powered on.  Note: If it isn't possible to
-#   attempt to made to restart Klipper after power on.
+#   schedule a firmware restart (ie: Klippy is disconnected), the restart
+#   will be postponed until Klippy reconnects and reports that startup is
+#   complete.  In this scenario, if Klippy reports that it is "ready", the
+#   FIRMWARE_RESTART will be aborted as unnecessary.
+#   The default is False.
+restart_delay: 1.
+#   If "restart_klipper_when_powered" is set, this option specifies the amount
+#   of time (in seconds) to delay the restart.  Default is 1 second.
 bound_service:
 #   Can be set to any service Moonraker is authorized to manage with the
 #   exception of the moonraker service itself. See the tip below this section
@@ -220,9 +298,6 @@ bound_service:
 #   been set the service will be started when the device powers on and stopped
 #   when the device powers off.  The default is no service is bound to the
 #   device.
-restart_delay: 1.
-#   If "restart_klipper_when_powered" is set, this option specifies the amount
-#   of time (in seconds) to delay the restart.  Default is 1 second.
 pin: gpiochip0/gpio26
 #   The pin to use for GPIO and RF devices.  The chip is optional, if left out
 #   then the module will default to gpiochip0.  If one wishes to invert
@@ -376,6 +451,8 @@ token: home-assistant-very-long-token
 domain: switch
 ```
 
+#### Toggling device state from Klipper
+
 It is possible to toggle device power from the Klippy host, this can be done
 with a gcode_macro, such as:
 ```ini
@@ -407,7 +484,53 @@ gcode:
   UPDATE_DELAYED_GCODE ID=delayed_printer_off DURATION=60
 ```
 
-## `[update_manager]`
+#### Power on G-Code Uploads
+
+The following is an example configuration that would fully automate
+the process of powering on a printer and loading a print from a
+Slicer upload with the "start" flag enabled.
+
+```ini
+# moonraker.conf
+
+# Configure the file manager to queue uploaded files when the "start" flag
+# is set and Klipper cannot immediately start the print.
+[file_manager]
+queue_gcode_uploads: True
+# Set the config_path and log_path options to the correct locations
+config_path:
+log_path:
+
+# Configure the Job Queue to start a queued print when Klipper reports as
+# ready.
+[job_queue]
+load_on_startup: True
+# Configure the job_transition_delay and job_transition_gcode options
+# if desired.  Note that they do no apply to prints loaded on startup.
+
+# Configure the "power" device to turn on when uploads are queued.
+[power printer]
+type: gpio
+pin: gpio26
+initial_state: off
+# Power the printer on when the file manager queues an upload
+on_when_upload_queued: True
+bound_service: klipper
+```
+
+With the above configuration options set, an upload with the "start"
+flag set to true will be queued.  This "printer" device will be
+notified and powered on.  Finally, the job_queue will load and start
+the queued print after Klipper reports itself as "ready".
+
+!!! Note
+    This procedure assumes that the printer is powered off when the
+    gcode file is uploaded.  It also assumes that the `job_queue` is
+    empty, if any jobs exist in the queue then the next job on the
+    queue will be loaded.
+
+
+### `[update_manager]`
 This enables moonraker's update manager.  Note that updates can only be
 performed on pristine git repos.  Repos that have been modified on
 disk or cloned from unofficial sources are not supported.
@@ -446,7 +569,7 @@ channel: dev
 #   removed during this process.  The default is dev.
 ```
 
-### Client Configuration
+#### Client Configuration
 This allows client programs such as Fluidd, KlipperScreen, and Mainsail to be
 updated in addition to klipper, moonraker, and the system os. Repos that have
 been modified or cloned from unofficial sources are not supported.
@@ -537,7 +660,7 @@ is_system_service: True
 #   repos that are not installed as a service.  The default is True.
 ```
 
-## `[mqtt]`
+### `[mqtt]`
 
 Enables an MQTT Client.  When configured most of Moonraker's APIs are availble
 by publishing JSON-RPC requests to `{instance_name}/moonraker/api/request`.

docs/web_api.md

@@ -2076,6 +2076,320 @@ deleted item.
 }
 ```
 
+### Job Queue APIs
+
+The following enpoints may be used to manage Moonraker's job queue.
+Note that Moonraker's Job Queue is impelemented as a FIFO queue and it may
+contain multiple references to the same job.
+
+!!! Note
+    All filenames provided to and returned by these endpoints are relative to
+    the `gcodes` root.
+
+#### Retrieve the job queue status
+
+Retreives the current state of the job queue
+
+HTTP request:
+```http
+GET /server/job_queue/status
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.job_queue.status",
+    "id": 4654
+}
+```
+
+Returns:
+
+The current state of the job queue:
+
+```json
+{
+    "queued_jobs": [
+        {
+            "filename": "job1.gcode",
+            "job_id": "0000000066D99C90",
+            "time_added": 1636151050.7666452,
+            "time_in_queue": 21.89680004119873
+        },
+        {
+            "filename": "job2.gcode",
+            "job_id": "0000000066D991F0",
+            "time_added": 1636151050.7766452,
+            "time_in_queue": 21.88680004119873
+        },
+        {
+            "filename": "subdir/job3.gcode",
+            "job_id": "0000000066D99D80",
+            "time_added": 1636151050.7866452,
+            "time_in_queue": 21.90680004119873
+        }
+    ],
+    "queue_state": "ready"
+}
+```
+
+Below is a description of the returned fields:
+
+- `queued_jobs`: an array of objects representing each queued job.  Each
+  object contains the `filename` of the enqueued job and a unique `job_id`
+  generated for each job.  The `job_id` is a 64-bit Hexadecimal string value.
+  On 32-bit systems the most significant bits will always contain zeros.  Items
+  are ordered by the time they were queued, the first item will be the next job
+  loaded.
+- `queue_state`: The current state of the queue.  Can be one of the following:
+    - `ready`: The queue is active and will load the next job upon completion
+      of the current job
+    - `loading`: The queue is currently loading the next job. If the user
+      specified a `job_transition_delay` and/or `job_transition_gcode`, the
+      queue will remain in the `loading` state until both are completed or
+      an error is encountered.
+    - `starting`: The queue enters this state after the `loading` phase is
+      complete before attempting to start the job.
+    - `paused`:  The queue is currently paused and will not load the next job
+      upon completion of the current job.  The queue will enter the `paused`
+      state if an error is encountered during the `loading` or `starting` phases,
+      or if the user pauses the queue through the provided endpoint.
+- `time_added`: The time (in Unix Time) the job was added to the queue
+- `time_in_queue`: The cumulative amount of time (in seconds) the job has been
+  pending in the queue
+
+#### Enqueue a job
+
+Adds a job, or an array of jobs, to the end of the job queue.  The same
+filename may be specified multiple times to queue a job that repeats.
+When multiple jobs are specfied they will be enqued in the order they
+are received.  If the queue is empty and in the `ready` state, the first
+job supplied will be started.
+
+!!! Note
+    The request will be aborted and return an error if any of the supplied
+    files do not exist.
+
+HTTP request:
+```http
+POST /server/job_queue/job?filenames=job1.gcode,job2.gcode,subdir/job3.gocde
+```
+
+!!! Note
+    Multiple jobs are should be comma separated as shown above.
+    Alternatively `filenames` maybe be specified as a json object
+    in the body of the request.
+
+```http
+POST /server/job_queue/job
+Content-Type: applicaton/json
+
+{
+    "filenames": [
+        "job1.gcode",
+        "job2.gcode",
+        "subdir/job3.gocde",
+    ]
+}
+```
+
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.job_queue.post_job",
+    "params": {
+        "filenames": [
+            "job1.gcode",
+            "job2.gcode",
+            "subir/job3.gocde",
+        ]
+    },
+    "id": 4654
+}
+```
+
+Returns:
+
+The current state of the job queue:
+
+```json
+{
+    "queued_jobs": [
+        {
+            "filename": "job1.gcode",
+            "job_id": "0000000066D99C90",
+            "time_added": 1636151050.7666452,
+            "time_in_queue": 21.89680004119873
+        },
+        {
+            "filename": "job2.gcode",
+            "job_id": "0000000066D991F0",
+            "time_added": 1636151050.7766452,
+            "time_in_queue": 21.88680004119873
+        },
+        {
+            "filename": "subdir/job3.gcode",
+            "job_id": "0000000066D99D80",
+            "time_added": 1636151050.7866452,
+            "time_in_queue": 21.90680004119873
+        }
+    ],
+    "queue_state": "ready"
+}
+```
+
+#### Remove a Job
+
+Removes one or more jobs from the queue.
+
+!!! Note
+    Unlike the POST version of this method, it is not necessary that
+    all job ids exist.  If any supplied job id does not exist in the
+    queue it will be silently ignored.  Clients can verify the contents
+    of the queue via the return value.
+
+HTTP request:
+```http
+DELETE /server/job_queue/job?job_ids=0000000066D991F0,0000000066D99D80
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.job_queue.delete_job",
+    "params": {
+        "job_ids": [
+            "0000000066D991F0".
+            "0000000066D99D80"
+        ]
+    },
+    "id": 4654
+}
+```
+!!! Tip
+    Alternatively `all=true` (`"all": true` for JSON-RPC) may specified
+    to clear the job queue.
+
+Returns:
+
+The current state of the job queue:
+
+```json
+{
+    "queued_jobs": [
+        {
+            "filename": "job1.gcode",
+            "job_id": "0000000066D99C90",
+            "time_added": 1636151050.7666452,
+            "time_in_queue": 21.89680004119873
+        }
+    ],
+    "queue_state": "ready"
+}
+```
+#### Pause the job queue
+
+Sets the job queue state to "pause", which prevents the next job
+in the queue from loading after an job in progress is complete.
+
+!!! Note
+    If the queue is paused while the queue is in the `loading` state
+    the load will be aborted.
+
+HTTP request:
+```http
+POST /server/job_queue/pause
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.job_queue.pause",
+    "id": 4654
+}
+```
+
+Returns:
+
+The current state of the job queue:
+
+```json
+{
+    "queued_jobs": [
+        {
+            "filename": "job1.gcode",
+            "job_id": "0000000066D99C90",
+            "time_added": 1636151050.7666452,
+            "time_in_queue": 21.89680004119873
+        },
+        {
+            "filename": "job2.gcode",
+            "job_id": "0000000066D991F0",
+            "time_added": 1636151050.7766452,
+            "time_in_queue": 21.88680004119873
+        },
+        {
+            "filename": "subdir/job3.gcode",
+            "job_id": "0000000066D99D80",
+            "time_added": 1636151050.7866452,
+            "time_in_queue": 21.90680004119873
+        }
+    ],
+    "queue_state": "paused"
+}
+```
+
+#### Resume the job queue
+
+Sets the job queue state to "resume".  This will set the job
+queue to state to "idle".  If the queue is not empty the next job
+in the queue will be loaded.
+
+HTTP request:
+```http
+POST /server/job_queue/resume
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.job_queue.resume",
+    "id": 4654
+}
+```
+
+Returns:
+
+The current state of the job queue:
+
+```json
+{
+    "queued_jobs": [
+        {
+            "filename": "job1.gcode",
+            "job_id": "0000000066D99C90",
+            "time_added": 1636151050.7666452,
+            "time_in_queue": 21.89680004119873
+        },
+        {
+            "filename": "job2.gcode",
+            "job_id": "0000000066D991F0",
+            "time_added": 1636151050.7766452,
+            "time_in_queue": 21.88680004119873
+        },
+        {
+            "filename": "subdir/job3.gcode",
+            "job_id": "0000000066D99D80",
+            "time_added": 1636151050.7866452,
+            "time_in_queue": 21.90680004119873
+        }
+    ],
+    "queue_state": "loading"
+}
+```
+
+
 ### Update Manager APIs
 The following endpoints are available when the `[update_manager]` component has
 been configured:
@@ -2928,6 +3242,38 @@ An object containing the following total job statistics:
 }
 ```
 
+#### Reset totals
+Resets the persistent "job totals" to zero.
+
+HTTP request:
+```http
+POST /server/history/reset_totals
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "server.history.reset_totals",
+    "id": 5534
+}
+
+Returns:
+
+The totals prior to the reset:
+
+```json
+{
+    "last_totals": {
+        "total_jobs": 3,
+        "total_time": 11748.077333278954,
+        "total_print_time": 11348.794790096988,
+        "total_filament_used": 11615.718840001999,
+        "longest_job": 11665.191012736992,
+        "longest_print": 11348.794790096988
+    }
+}
+```
+
 #### Get a single job
 HTTP request:
 ```http