update readme, update docs

README.md

@@ -2,29 +2,36 @@
 
 Cross platform command line application to run health checks against sensor stations registered on [openSenseMap.org](https://opensensemap.org).
 
-This tool quickly runs various health checks on selected senseBoxes,
+This tool lets you automatically check if senseBoxes are still runnning correctly,
-and can send out notifications via various protocols.
+and when that's not the case, notifies you.
-Specifically email is implemented, but other transports can be added easily.
+Currently, email notifications are implemented, but other transports can be added easily.
+Implemented health checks are [described below](#possible-values-for-defaulthealthchecksevents), and new ones can be added just as easily (given some knowledge of programming).
 
-The tool can also operate in watch mode, checking boxes at regular intervals.
+The tool has multiple modes of operation:
 
-Check the manual in the [doc/](doc/osem_notify.md) directory for a description of features.
+- `osem_notify check boxes`: run one-off checks on boxes
+- `osem_notify watch boxes`: check boxes continuously
+
+Run `osem_notify help` or check the manual in the [docs/](docs/osem_notify.md) directory for more details.
 
 ## get it
-Download a build from the [releases page](releases/).
+Download a build from the [releases page](https://github.com/noerw/osem_notify/releases/).
-You can immediately call the application by running `./osem_notify` in a terminal in your downloads directory.
+You can run the application by running `./osem_notify*` in a terminal in your downloads directory.
 
-On unix platforms you may add it to your path for convenience, so it is always callable via `osem_notify`:
+On unix platforms you may need to make it executable, and can add it to your `$PATH` for convenience, so it is always callable via `osem_notify`:
 ```sh
-sudo mv osem_notify /usr/bin/osem_notify
+chmod +x osem_notify*
+sudo mv osem_notify* /usr/bin/osem_notify
 ```
 
 ## configure it
-Configuration is required to set up notification transports, and can set the default healthchecks.
+The tool works out of the box for basic functionality, but must be configured to set up notifications.
+
 Configuration can be done via a YAML file located at `~/.osem_notify.yml` or through environment variables.
 Example configuration:
 
 ```yaml
+# override default health checks:
 defaultHealthchecks:
   notifications:
     transport: email
@@ -49,14 +56,14 @@ email:
   from: hildegunst@example.com
 ```
 
-### possible values for `notifications`:
+### possible values for `defaultHealthchecks.notifications`:
 `transport` | `options`
 ------------|------------
 `email`     | `recipients`: list of email addresses
 
 Want more? [add it](#contribute)!
 
-### possible values for `events[]`:
+### possible values for `defaultHealthchecks.events[]`:
 
 `type`               | description
 ---------------------|------------
@@ -71,8 +78,9 @@ Want more? [add it](#contribute)!
 ### configuration via environment variables
 Instead of a YAML file, you may configure the tool through environment variables. Keys are the same as in the YAML, but:
 
-- prefixed with `osem_notify_`
+- prefixed with `OSEM_NOTIFY_`
 - path separator is not `.`, but `_`
+- all upper case
 
 Example: `OSEM_NOTIFY_EMAIL_PASS=supersecret osem_notify check boxes`
 
@@ -92,7 +100,7 @@ Contributions are welcome!
 Check out the following locations for plugging in new functionality:
 
 - new notification transports: [core/notifiers.go](core/notifiers.go)
-- new health checks: [core/Box.go](core/Box.go)
+- new health checks: [core/healthcheck*.go](core/healtchecks.go)
 - new commands: [cmd/](cmd/)
 
 Before committing and submitting a pull request, please run `go fmt ./ cmd/ core/`.

docs/osem_notify.md

@@ -13,17 +13,22 @@ osem_notify [flags]
 ### Options
 
 ```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
   -c, --config string      path to config file (default $HOME/.osem_notify.yml)
   -d, --debug              enable verbose logging
   -h, --help               help for osem_notify
   -l, --logformat string   log format, can be plain or json (default "plain")
   -n, --notify             if set, will send out notifications.
-                           Otherwise results are printed to stdout only
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
 ```
 
 ### SEE ALSO
 
 * [osem_notify check](osem_notify_check.md)	 - One-off check for events on boxes
+* [osem_notify debug](osem_notify_debug.md)	 - Run some debugging checks on osem_notify itself
+* [osem_notify version](osem_notify_version.md)	 - Get build and version information
 * [osem_notify watch](osem_notify_watch.md)	 - Watch boxes for events at an interval
 
-###### Auto generated by spf13/cobra on 24-Jun-2018
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_check.md

@@ -15,11 +15,14 @@ One-off check for events on boxes
 ### Options inherited from parent commands
 
 ```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
   -c, --config string      path to config file (default $HOME/.osem_notify.yml)
   -d, --debug              enable verbose logging
   -l, --logformat string   log format, can be plain or json (default "plain")
   -n, --notify             if set, will send out notifications.
-                           Otherwise results are printed to stdout only
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
 ```
 
 ### SEE ALSO
@@ -27,4 +30,4 @@ One-off check for events on boxes
 * [osem_notify](osem_notify.md)	 - Root command displaying help
 * [osem_notify check boxes](osem_notify_check_boxes.md)	 - one-off check on one or more box IDs
 
-###### Auto generated by spf13/cobra on 24-Jun-2018
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_check_boxes.md

@@ -19,15 +19,18 @@ osem_notify check boxes <boxId> [...<boxIds>] [flags]
 ### Options inherited from parent commands
 
 ```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
   -c, --config string      path to config file (default $HOME/.osem_notify.yml)
   -d, --debug              enable verbose logging
   -l, --logformat string   log format, can be plain or json (default "plain")
   -n, --notify             if set, will send out notifications.
-                           Otherwise results are printed to stdout only
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
 ```
 
 ### SEE ALSO
 
 * [osem_notify check](osem_notify_check.md)	 - One-off check for events on boxes
 
-###### Auto generated by spf13/cobra on 24-Jun-2018
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_debug.md

@@ -0,0 +1,37 @@
+## osem_notify debug
+
+Run some debugging checks on osem_notify itself
+
+### Synopsis
+
+osem_notify debug <feature> tests the functionality of the given feature
+
+```
+osem_notify debug [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for debug
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
+  -d, --debug              enable verbose logging
+  -l, --logformat string   log format, can be plain or json (default "plain")
+  -n, --notify             if set, will send out notifications.
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
+```
+
+### SEE ALSO
+
+* [osem_notify](osem_notify.md)	 - Root command displaying help
+* [osem_notify debug notifications](osem_notify_debug_notifications.md)	 - Verify that notifications are working
+
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_debug_notifications.md

@@ -0,0 +1,36 @@
+## osem_notify debug notifications
+
+Verify that notifications are working
+
+### Synopsis
+
+osem_notify debug <feature> tests the functionality of the given feature
+
+```
+osem_notify debug notifications [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for notifications
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
+  -d, --debug              enable verbose logging
+  -l, --logformat string   log format, can be plain or json (default "plain")
+  -n, --notify             if set, will send out notifications.
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
+```
+
+### SEE ALSO
+
+* [osem_notify debug](osem_notify_debug.md)	 - Run some debugging checks on osem_notify itself
+
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_version.md

@@ -0,0 +1,36 @@
+## osem_notify version
+
+Get build and version information
+
+### Synopsis
+
+osem_notify version returns its build and version information
+
+```
+osem_notify version [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for version
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
+  -c, --config string      path to config file (default $HOME/.osem_notify.yml)
+  -d, --debug              enable verbose logging
+  -l, --logformat string   log format, can be plain or json (default "plain")
+  -n, --notify             if set, will send out notifications.
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
+```
+
+### SEE ALSO
+
+* [osem_notify](osem_notify.md)	 - Root command displaying help
+
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_watch.md

@@ -16,11 +16,14 @@ Watch boxes for events at an interval
 ### Options inherited from parent commands
 
 ```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
   -c, --config string      path to config file (default $HOME/.osem_notify.yml)
   -d, --debug              enable verbose logging
   -l, --logformat string   log format, can be plain or json (default "plain")
   -n, --notify             if set, will send out notifications.
-                           Otherwise results are printed to stdout only
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
 ```
 
 ### SEE ALSO
@@ -28,4 +31,4 @@ Watch boxes for events at an interval
 * [osem_notify](osem_notify.md)	 - Root command displaying help
 * [osem_notify watch boxes](osem_notify_watch_boxes.md)	 - watch a list of box IDs for events
 
-###### Auto generated by spf13/cobra on 24-Jun-2018
+###### Auto generated by spf13/cobra on 26-Jun-2018

docs/osem_notify_watch_boxes.md

@@ -19,16 +19,19 @@ osem_notify watch boxes <boxId> [...<boxIds>] [flags]
 ### Options inherited from parent commands
 
 ```
+  -a, --api string         openSenseMap API to query against (default "https://api.opensensemap.org")
   -c, --config string      path to config file (default $HOME/.osem_notify.yml)
   -d, --debug              enable verbose logging
   -i, --interval int       interval to run checks in minutes (default 15)
   -l, --logformat string   log format, can be plain or json (default "plain")
   -n, --notify             if set, will send out notifications.
-                           Otherwise results are printed to stdout only
+                           Otherwise results are printed to stdout only.
+                           You might want to run 'osem_notify debug notifications' first to verify everything works.
+                           
 ```
 
 ### SEE ALSO
 
 * [osem_notify watch](osem_notify_watch.md)	 - Watch boxes for events at an interval
 
-###### Auto generated by spf13/cobra on 24-Jun-2018
+###### Auto generated by spf13/cobra on 26-Jun-2018