style: maintain docs and fix repository ameba failures (#312)

* ci: use crystal 1.4.0

* docs: fix spelling mistakes, add section links, reword slightly

* style: resolve ameba issues

* style: use `when`/`in` followed by `then`

* ci: remove 1.4.x until we build them

.ameba.yml

@@ -1,6 +1,10 @@
 Excluded:
   - repositories/**/*.cr
 
+Lint/DebugCalls:
+  Excluded:
+  - drivers/**/*_spec.cr
+
 # NOTE: These should all be reviewed on an individual basis to see if their
 #       complexity can be reasonably reduced.
 Metrics/CyclomaticComplexity:

.github/workflows/ci.yml

@@ -35,7 +35,6 @@ jobs:
       matrix:
         stable: [true]
         crystal:
-          - 1.0.0
           - 1.1.1
         include:
           - stable: false
@@ -74,7 +73,6 @@ jobs:
       matrix:
         stable: [true]
         crystal:
-          - 1.0.0
           - 1.1.1
         include:
           - stable: false

README.md

@@ -43,6 +43,16 @@ Before committing, please run...
 $ ./harness format
 ```
 
+## Documentation
+
+- [Writing a PlaceOS Driver](docs/writing-a-driver.md)
+- [Testing a PlaceOS Driver](docs/writing-a-spec.md)
+- [Sending Emails](docs/guide-event-emails.md)
+- [Environment Setup](docs/setup.md)
+- [Runtime Debugging](docs/runtime-debugging.md)
+- [Directory Structure](docs/directory_structure.md)
+- [PlaceOS Spec Runner HTTP API](docs/http-api.md)
+
 ## Contributing
 
 1. [Fork it](https://github.com/PlaceOS/drivers/fork)

docker-compose.yml

@@ -2,7 +2,7 @@ version: "3.7"
 services:
   # Driver test harness
   drivers:
-    image: placeos/drivers-spec:crystal-${CRYSTAL_VERSION:-1.1.1}
+    image: placeos/drivers-spec:crystal-${CRYSTAL_VERSION:-1.4.0}
     restart: always
     container_name: placeos-drivers
     hostname: drivers
@@ -35,7 +35,7 @@ services:
 
   # Ensures shards are installed.
   install-shards:
-    image: crystallang/crystal:${CRYSTAL_VERSION:-1.1.1}-alpine
+    image: crystallang/crystal:${CRYSTAL_VERSION:-1.4.0}-alpine
     restart: "no"
     working_dir: /wd
     command: ash -c 'shards check -q || shards install'

docs/directory_structure.md

@@ -1,9 +1,11 @@
 # Directory Structures
 
-PlaceOS core / drivers makes the assumption that the working directory one level
-up from the scratch directory. An example deployment structure:
+[PlaceOS Core](https://github.com/PlaceOS/core) and [PlaceOS Driver Spec Runner](https://github.com/PlaceOS/driver-spec-runner) make the assumption that the working directory is one level
+up from the `drivers` directory.
 
-* Working dir: `/home/placeos/core`
+An example deployment structure:
+
+* Working directory: `/home/placeos/core`
 * Executable: `/home/placeos/core/bin/core`
 * Driver repositories: `/home/placeos/repositories`
   * PlaceOS Drivers: `/home/placeos/repositories/drivers`
@@ -12,9 +14,10 @@ up from the scratch directory. An example deployment structure:
 
 However when developing the structure will look more like:
 
-* Working dir: `/home/steve/drivers`
-* Driver repository: `/home/steve/drivers`
-* Driver executables: `/home/steve/drivers/bin/drivers`
+* Working directory: `/home/placeos/drivers`
+* Driver repository: `/home/placeos/drivers`
+* Driver executables: `/home/placeos/drivers/bin/drivers`
   * Samsung driver: `/home/placeos/core/bin/drivers/353b53_samsung_display_md_series_cr`
 
-The primary difference between production and development is PlaceOS core, in production, will be cloning repositories and installing shards as required.
+The primary difference between production and development is [PlaceOS Core](https://github.com/PlaceOS/core).
+In a production environment, PlaceOS Core handles cloning repositories, installing packages, and building Drivers as required.

docs/guide-event-emails.md

@@ -2,12 +2,13 @@
 
 There are three aspects to this
 
-1. real-time send an email as soon as an event occurs
-2. batching events (either periodically or via a CRON)
-3. managing state (state machine management)
+1. Sending an email in real-time as an event occurs
+2. Batching events (either periodically or via a [CRON](https://crontab.guru/))
+3. Managing state (state machine management)
 
-i.e. send email straight away if the event is today otherwise send them at 7am every morning and mark emails as sent.
-Poll every 15min to send any emails that were missed due to an outage. (by checking state)
+For example...
+- Send an email straight away if the event is today, otherwise, send them at 7 am every morning and mark the emails as sent.
+- Poll every 15min to send any emails that were missed due to an outage (by checking state)
 
 
 ## Example logic driver
@@ -77,7 +78,7 @@ class DeskBookingNotification < PlaceOS::Driver
   end
 
   # ensure we don't have two fibers processing this at once
-  # (technically the driver is thread safe, but it is concurrent)
+  # (technically the driver is thread-safe, but it is concurrent)
   @check_bookings_mutex = Mutex.new
 
   @[Security(Level::Support)]
@@ -435,7 +436,7 @@ email_templates:
         Please reach out to your <a
         href="mailto:%{support_email}?subject=%{building_name} workplace
         question">workplace support team</a> should you have any other queries,
-        otherwise we look forward to seeing you soon
+        otherwise, we look forward to seeing you soon
 
         </body></html>
 

docs/setup.md

@@ -1,37 +1,17 @@
 # Setup
 
-This allows you to build and test drivers without installing or running the complete PlaceOS service.
+Usage of [PlaceOS Driver Spec Runner](https://github.com/PlaceOS/driver-spec-runner) allows you to build and test
+drivers without installing or running the complete PlaceOS service.
 
-1. clone the drivers repository: `git clone https://github.com/placeos/drivers drivers`
-2. clone private repositories here: `mkdir ./drivers/repositories`
+## Installation
 
+Clone the drivers repository: `git clone https://github.com/placeos/drivers drivers`
 
-## OSX
+## Reports
 
-Install [Homebrew](https://brew.sh/) to install dependencies
+Test your driver with `./harness report <your_spec_file>`.
+If the spec file argument is omitted, the harness will run specs for every driver in the current repository.
 
-* Install [Crystal Lang](https://crystal-lang.org/reference/installation/): `brew install crystal`
-* Install libssh2: `brew install libssh2`
-* Install redis: `brew install redis`
+## Developing
 
-Ensure the following lines are in your `.bashrc` file
-
-```shell
-export PATH="/usr/local/opt/llvm/bin:$PATH"
-export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/opt/openssl/lib/pkgconfig
-```
-
-
-## Running Specs
-
-1. Ensure redis is running: `redis-server`
-2. Install dependencies: `cd drivers; shards update`
-3. Launch application: `crystal run ./src/app.cr`
-4. Browse to: http://localhost:3000/
-
-Now you can build drivers and run specs:
-
-* Build a drvier or spec: `curl -X POST "http://localhost:3000/build?driver=drivers/helvar/net.cr"`
-* Run a spec: `curl -X POST "http://localhost:3000/test?driver=drivers/lutron/lighting.cr&spec=drivers/lutron/lighting_spec.cr"`
-
-To build or test against drivers in private repositories include the repository param: `repository=private_drivers`
+After running `./harness up`, the harness will expose a development interface on [localhost:8085](http://localhost:8085).