Updating and cleaning up documentation

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2021 Wayne Manselle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.

README.md

@@ -1,115 +1,170 @@
 # purple_exporter
 
-purple_exporter is a basic Prometheus exporter that exports information from
-a single PAII Purple Air Sensor.
+[![MIT Licensed][license-badge]][license-url]
+
+[license-badge](https://img.shields.io/badge/License-MIT-yellow.svg)
+[license-url](https://opensource.org/licenses/MIT)]
+
+Exporting metrics from the PurpleAir API for your PurpleAir Sensor.
+
+This is where a link to the latest relase will go.
+
+## Table of Contents
+
+1. [Description](#description)
+2. [Technical Details](#technical-details)
+  2.1 [Exposed Metrics](#exposed-metrics)
+    2.1.1 [Environmental Data](#environmental-data)
+    2.1.2 [Estimated Mass Concentrations](#estimated-mass-concentrations)
+    2.1.3 [Particle Concentrations](#particle-concentrations)
+3. [Building Purple Exporter](#building-purple-exporter)
+  3.1 [Getting an API Key](#getting-an-api-key)
+  3.2 [Building from Source](#building-from-source)
+  3.3 [Building Docker Image](#building-docker-image)
+4. [Required Configuration](#required-configuration)
+  4.1 [Sensor Index](#sensor-index)
+  4.2 [API Read Key](#api-read-key)
+  4.3 [Request Rate](#request-rate)
+  4.4 [Network Port](#network-port)
+  4.5 [Environmental Adjustment](#environmental-adjustment)
+  4.6 [Log Level](log-level)
+5. [Running Purple Exporter](#running-purple-exporter)
+  5.1 [Running from Source](#running-from-source)
+  5.2 [Running from Executable](#running-from-executable)
+  5.3 [Running from Docker](#running-from-docker)
+6. [Testing](#testing)
+7. [License](#license)
+8. [References](#references)
+
+## Description
+
+purple_exporter is a Prometheus exporter that exports a subset of available
+information from a single
+[PAII Purple Air Sensor](https://www2.purpleair.com/products/purpleair-pa-ii).
 
 This project was developed so I could pipe the information from my own PAII
 sensor to a grafana chart I run in my house. In the future, I may expand the
 usability of this exporter to other PA sensors, or ranges of sensors.
 
-## Getting the Required API Key
+## Technical Details
 
-- A PurpleAir API Key
+### Exposed Metrics
+
+Metrics are collected from all sensors for which they are available.
+
+#### Environmental Data
+
+- Humidity: Relative humidity in the sensor chamber, on average, 4% lower than ambient humidity
+- Temperature: Temperature in the sensor chamber in Farenheit, on average 8F higher than ambient temperature
+- Air Pressure: Current pressure in millibars
+
+#### Estimated Mass Concentrations
+
+- pm1.0: Estimated mass concentration of particles less than 1 uM in diameter. (ug/m)
+- pm2.5: Estimated mass concentration of particles less than 2.5 uM in diameter. (ug/m)
+- pm10.0: Estimated mass concentration of particles less than 10.0 uM in diameter. (ug/m)
+
+#### Partical Concentrations
+
+- 0.3um: Count of particles greater than 0.3 uM in diameter. (particles/100mL)
+- 0.5um: Count of particles greater than 0.5 uM in diameter. (particles/100mL)
+- 1.0um: Count of particles greater than 1.0 uM in diameter. (particles/100mL)
+- 2.5um: Count of particles greater than 2.5 uM in diameter. (particles/100mL)
+- 5.0um: Count of particles greater than 5.0 uM in diameter. (particles/100mL)
+- 10.0um: Count of particles greater than 10.0 uM in diameter. (particles/100mL)
+
+## Building Purple Exporter
+
+### Getting an API Key
 
 In order to use the exporter, one will need a PurpleAir API key. This can be
 obtained by e-mailing [contact@purpleair.com](mailto:contact@purpleair.com).
 Approved applications will receive a read key, and a write key. This exporter
 only makes use of the read key to retrieve information from the specified
 sensor.
 
-## Running the Exporter
+### Building From Source
+
+`cargo build --release`
+
+The resulting executable will be placed in `<path_to_repo>/target/release/`.
+
+### Building Docker Image
+
+If running from the repository root:
+`docker build -t <tag> .`
+
+This will result in a trimmed down alpine linux image with a statically compiled executable.
 
-### Configuring the Exporter
+## Required Configuration
 
 The exporter is configurable using the values below, specified via environmental
 variable, or command line argument.
 
-#### Sensor Index
+### Sensor Index
 
 Set with the `SENSOR_ID` environment variable, or the `-s` flag.
 This value is the unique index assigned by PurpleAir to the sensor that readings
 will be drawn from.
 
-#### API Read Key
+### API Read Key
 
 Set with the `READ_KEY` environment variable, or the `-x` flag.
 This is one of the two API keys PurpleAir will furnish when following the above
 directions.
 
-#### Request Rate
+### Request Rate
 
 Set with the `REQUEST_RATE` environment variable, or the `-r` flag.
 This is how often to query the purple air API, in seconds. This will
 default to a minimum of once every 300 seconds (5 minutes).
 
-#### Network Port
+### Network Port
 
 Set with the `PORT` environment variable, or the `-p` flag.
 This is the network port the exporter will serve its data from.
 
-#### Environmental Adjustment
+### Environmental Adjustment
 
 Set with the `ADJUST` environment variable, or the `-a` flag.
 This flag is used to indicate whether humidity and temperature readings
 should be adjusted to reflect likely ambient readings rather than readings in
 the sensor housing. Sensor readings are, on average, 8F hotter and 4% drier.
 Valid values are `true` or `false`, and will default to `false`.
 
-### Running the exporter from Cargo
+### Log Level
 
-`cargo run -- -r rate -s sensor_index -x API_read_key -p port -a adjust`
+Set with `RUST_LOG` to indicate which level of messages to log when running
+purple_exporter. Options include: `info` or `trace`.
 
-### Building the Purple Exporter as an executable
+## Running the Exporter
 
-`cargo build --release`
+### Running from Source
 
-The resulting executable will be placed in `<path_to_repo>/target/release/`.
+`cargo run -- -r rate -s sensor_index -x API_read_key -p port -a adjust`
 
-### Building the Docker Image
+### Running from Executable
 
-If running from the repository root:
-`docker build -t <tag> .`
+`./purple_exporter -r rate -s sensor_index -x API_read_key -p port -a adjust`
 
-This will result in a trimmed down alpine linux image with a statically compiled executable.
+or by setting environment variables.
 
 ### Running the Docker Image
 
 `docker run --env-file .env <image>`
 
 An example environment variable file is provided in `.env.example`.
 
-### Exporter Logging
-
-Purple Exporter makes use of seanmonstar's [pretty-env-logger](https://github.com/seanmonstar/pretty-env-logger) to
-provide activity logging.  In order to utilize this logging, set an environment
-variable, `RUST_LOG` to `info` or `trace` before executing cargo run as
-illustrated above.
-
-### Exposed Metrics
-
-Metrics are collected from all sensors for which they are available.
-
-#### Environmental Data
+## Testing
 
-- Humidity: Relative humidity in the sensor chamber, on average, 4% lower than ambient humidity
-- Temperature: Temperature in the sensor chamber in Farenheit, on average 8F higher than ambient temperature
-- Air Pressure: Current pressure in millibars
+Work in Progress
 
-#### Estimated Mass Concentrations
-
-- pm1.0: Estimated mass concentration of particles less than 1 uM in diameter. (ug/m)
-- pm2.5: Estimated mass concentration of particles less than 2.5 uM in diameter. (ug/m)
-- pm10.0: Estimated mass concentration of particles less than 10.0 uM in diameter. (ug/m)
+## License
 
-#### Partical Concentrations
-
-- 0.3um: Count of particles greater than 0.3 uM in diameter. (particles/100mL)
-- 0.5um: Count of particles greater than 0.5 uM in diameter. (particles/100mL)
-- 1.0um: Count of particles greater than 1.0 uM in diameter. (particles/100mL)
-- 2.5um: Count of particles greater than 2.5 uM in diameter. (particles/100mL)
-- 5.0um: Count of particles greater than 5.0 uM in diameter. (particles/100mL)
-- 10.0um: Count of particles greater than 10.0 uM in diameter. (particles/100mL)
+[LICENSE](./LICENSE)
 
 ## References
 
-[PurpleAir API docs](https://api.purpleair.com/#api-welcome)
+- [PurpleAir API docs](https://api.purpleair.com/#api-welcome)
+- Purple_Exporter makes use of seanmonstar's [pretty-env-logger](https://github.com/seanmonstar/pretty-env-logger) to
+provide activity logging.