[DOC] General documentation fixes, using Vale's Google style guide (#211

)

.github/ISSUE_TEMPLATE/feature_request.md

@@ -4,9 +4,15 @@ about: Suggest an idea for this project
 
 ---
 
+<!-- vale Google.FirstPerson = NO -->
+<!-- vale Google.Ellipses = NO -->
+
 **Is your feature request related to a problem? Please describe.**
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
+<!-- vale Google.FirstPerson = YES -->
+<!-- vale Google.Ellipses = YES -->
+
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 

.github/pull_request_template.md

@@ -1,7 +1,10 @@
 ## Description:
 
+<!-- vale Google.FirstPerson = NO -->
 
 ## Checklist:
   - [ ] The pull request is done against the latest development branch
   - [ ] Only one feature/fix was added per PR and the code change compiles without warnings
   - [ ] I accept the [DCO](https://github.com/theengs/gateway/blob/development/docs/participate/development.md#developer-certificate-of-origin).
+
+<!-- vale Google.FirstPerson = YES -->

.gitignore

@@ -131,3 +131,6 @@ dmypy.json
 
 # VuePress
 node_modules/
+
+# Vale styles
+vale/styles/Google

.pre-commit-config.yaml

@@ -4,6 +4,10 @@ repos:
   rev: 'v2.30.0'
   hooks:
     - id: vale
+      name: vale-sync
+      pass_filenames: false
+      args: [sync]
+    - id: vale
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: 'v0.1.9'
   hooks:

.vale.ini

@@ -1,5 +1,10 @@
 StylesPath = "vale/styles"
-MinAlertLevel = error
+MinAlertLevel = warning
 Vocab = Theengs
+Packages = Google
+
 [*.md]
-BasedOnStyles = Vale
+BasedOnStyles = Vale, Google
+Google.Headings = NO
+Google.WordList = NO
+Google.We = NO

CODE_OF_CONDUCT.md

@@ -34,13 +34,10 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. The project team reviews and investigates all complaints, and responds in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+This Code of Conduct is adapted from the [Contributor Covenant homepage](https://contributor-covenant.org), [version 1.4](https://contributor-covenant.org/version/1/4/).

README.md

@@ -1,15 +1,15 @@
-**Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder).
-It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html); LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, MiFlora... translates this information into a readable JSON format and pushes those to an MQTT broker.
+**Theengs Gateway** is a multi-platform, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder).
+It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html), including the LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, and MiFlora, and translates this information into a readable JSON format and pushes those to an MQTT broker.
 
 Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/), [ioBroker](https://www.iobroker.net/) or [Domoticz](https://domoticz.com/).
 
-The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging Python and multi platform libraries.
+The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop, or server by leveraging Python and multi-platform libraries.
 
 ![Gateway](https://github.com/theengs/home/raw/development/docs/img/Theengs-gateway-raspberry-pi.jpg)
 
-**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway.
+**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway home automation BLE sensors integration also works with Theengs Gateway.
 
-The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro and many more.
+The gateway retrieves data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro and many more.
 
 Full documentation for installation and usage can be found [here](https://theengs.github.io/gateway)
 
@@ -34,9 +34,9 @@ python3 -m TheengsGateway -h
 
 Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories -> Fill in the URL `https://github.com/mihsu81/addon-theengsgw` -> Add.
 
-2. You should now see "TheengsGateway HA Add-on" at the bottom list.
-3. Click on "TheengsGateway", then click "Install".
-4. Under the "Configuration" tab, change the settings appropriately (at least MQTT parameters), see [Parameters](#parameters).
+2. You should now see **TheengsGateway HA Add-on** at the bottom list.
+3. Click on **TheengsGateway**, then click **Install**.
+4. Under the **Configuration** tab, change the settings appropriately (at least MQTT parameters), see [Parameters](#parameters).
 5. Start the Add-on.
 
 ## Install Theengs Gateway as a snap

docs/README.md

@@ -4,14 +4,14 @@ title: Theengs BLE MQTT gateway
 # Theengs BLE MQTT gateway
 
 **Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder).
-It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html); LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, MiFlora... translates this information into a readable JSON format and pushes those to an MQTT broker.
+It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html), including the LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, and MiFlora, and translates this information into a readable JSON format and pushes those to an MQTT broker.
 
 Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/), [ioBroker](https://www.iobroker.net/) or [Domoticz](https://domoticz.com/).
 
-The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging Python and multi-platform libraries.
+The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop, or server by leveraging Python and multi-platform libraries.
 
 ![Gateway](https://github.com/theengs/home/raw/development/docs/img/Theengs-gateway-raspberry-pi.jpg)
 
-**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway.
+**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway home automation BLE sensors integration also works with Theengs Gateway.
 
-The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more.
+The gateway retrieves data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more.

docs/install/install.md

@@ -29,9 +29,9 @@ python3 -m TheengsGateway -h
 
 Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories -> Fill in the URL `https://github.com/mihsu81/addon-theengsgw` -> Add.
 
-2. You should now see "TheengsGateway HA Add-on" at the bottom list.
-3. Click on "TheengsGateway", then click "Install".
-4. Under the "Configuration" tab, change the settings appropriately (at least MQTT parameters), see [Parameters](https://github.com/mihsu81/addon-theengsgw/blob/main/theengsgateway/DOCS.md#parameters).
+2. You should now see **TheengsGateway HA Add-on** at the bottom list.
+3. Click on **TheengsGateway**, then click **Install**.
+4. Under the **Configuration** tab, change the settings appropriately (at least MQTT parameters), see [Parameters](https://github.com/mihsu81/addon-theengsgw/blob/main/theengsgateway/DOCS.md#parameters).
 5. Start the Add-on.
 
 ## Install Theengs Gateway as a snap

docs/participate/adding-decoders.md

@@ -1,5 +1,5 @@
 # Adding decoders
 
-Adding your device protocol to Theengs enable to increase interoperability and to create new use cases with your device. You will find below some guidance to do that. 
+Adding your device protocol to Theengs enables you to increase interoperability and to create new use cases with your device. Below is some guidance to do that. 
 
 You can do a pull request directly to the [Decoder Repository](https://github.com/theengs/decoder) by leveraging the Theengs Decoder [example](https://theengs.github.io/decoder/participate/adding-decoders.html).

docs/participate/development.md

@@ -14,7 +14,7 @@ agree to follow the [code of conduct](https://github.com/theengs/gateway/blob/ma
 * Request for review.
 * We may suggest some changes, improvements or alternatives.
 
-Some things that will increase the chance that your pull request is accepted:
+Some things that increase the chance that your pull request is accepted:
 
 * Comment your code.
 * Ask eventually for design guidelines.

docs/participate/support.md

@@ -1,8 +1,8 @@
 # Supporting the project
 
-If you like the project and/or used it please consider supporting it! It can be done in different ways:
+If you like the project and/or use it, please consider supporting us. It can be done in different ways:
 * Helping others in the [community](https://github.com/theengs/gateway/discussions)
 * [Contribute](development) to the [code](https://github.com/theengs/gateway) or the documentation,
 * Buy devices, boards or parts from the [compatible web site](https://compatible.openmqttgateway.com), the devices and parts linked use affiliated links,
 * Donate or sponsor the project [developers](https://github.com/theengs/gateway/graphs/contributors)
-* Make a video or a blog article about what you have done with [TheengsGateway](https://github.com/theengs/gateway) and share it.
+* Make a video or a blog article about what you have done with [TheengsGateway](https://github.com/theengs/gateway) and share it.

docs/prerequisites/broker.md

@@ -1,5 +1,5 @@
 # Broker
-The broker will act as an intermediary between TheengsGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism.
+The broker acts as an intermediary between TheengsGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism.
 
 All the events or commands could pass by the broker.
 

docs/prerequisites/controller.md

@@ -1,5 +1,5 @@
 # Controller
-MQTT enables you to connect easily a controller so as to monitor, control and automate scenarios.
+MQTT enables you to connect easily a controller so as to monitor, control, and automate scenarios.
 
 The following controllers (and many other software) are compatible with MQTT: