[DOCS] Further documentation fixes by enabling Google style suggestio…

…ns (#212)
theengs · Jan 5, 2024 · 2fb5c9d · 2fb5c9d
1 parent 86fbf07
commit 2fb5c9d
Show file tree

Hide file tree

Showing 12 changed files with 65 additions and 58 deletions.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -4,15 +4,9 @@ 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.
 

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,10 +1,6 @@
 ## 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 -->
+  - [ ] I have created the pull request against the latest development branch
+  - [ ] I have added only one feature/fix per PR and the code change compiles without warnings
+  - [ ] I accept the [Developer Certificate of Origin (DCO)](https://github.com/theengs/gateway/blob/development/docs/participate/development.md#developer-certificate-of-origin).
diff --git a/.vale.ini b/.vale.ini
@@ -1,10 +1,13 @@
 StylesPath = "vale/styles"
-MinAlertLevel = warning
+MinAlertLevel = suggestion
 Vocab = Theengs
 Packages = Google
 
 [*.md]
 BasedOnStyles = Vale, Google
+Google.Ellipses = NO
+Google.FirstPerson = NO
 Google.Headings = NO
+Google.Parens = NO
 Google.WordList = NO
 Google.We = NO
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,3 +1,5 @@
+<!-- vale Google.Passive = NO -->
+
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -11,7 +13,7 @@ Examples of behavior that contributes to creating a positive environment include
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
 * Gracefully accepting constructive criticism
-* Focusing on what is best for the community
+* Focusing on what's best for the community
 * Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
@@ -26,7 +28,7 @@ Examples of unacceptable behavior by participants include:
 
 Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that aren't aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
 ## Scope
 
@@ -36,7 +38,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 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.
+Project maintainers who don't 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
 

diff --git a/README.md b/README.md
@@ -1,17 +1,17 @@
-**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.
+**Theengs Gateway** is a multi-platform, multi devices Bluetooth Low Energy (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, 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/).
+Enabling integration to Internet of Things (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.
 
 ![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 also works with Theengs Gateway.
+You can use **Theengs Gateway** 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 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)
+You can find full documentation for installation and usage [here](https://theengs.github.io/gateway)
 
 ## Install Theengs Gateway as a pip package
 Prerequisites:

diff --git a/docs/README.md b/docs/README.md
@@ -1,17 +1,20 @@
 ---
 title: Theengs BLE MQTT gateway
 ---
+
+<!-- vale Google.Acronyms = NO -->
 # Theengs BLE MQTT gateway
+<!-- vale Google.Acronyms = YES-->
 
-**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), 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.
+**Theengs Gateway** is a multi-platform, multi devices Bluetooth Low Energy (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, 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/).
+Enabling integration to Internet of Things (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.
 
 ![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 also works with Theengs Gateway.
+You can use **Theengs Gateway** 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 retrieves data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more.
diff --git a/docs/participate/development.md b/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 increase the chance that your pull request is accepted:
+The following things increase the chance that we accept your pull request:
 
 * Comment your code.
 * Ask eventually for design guidelines.
@@ -48,8 +48,12 @@ Some things that increase the chance that your pull request is accepted:
         this project or the open source license(s) involved.
 ```
 
-This Developer Certificate Of Origin (DCO) was adopted on February 26, 2022.
+<!-- vale Google.Passive = NO -->
 
-The text of this license is available under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://creativecommons.org/licenses/by-sa/3.0/).  It is based on the Linux [Developer Certificate Of Origin](http://elinux.org/Developer_Certificate_Of_Origin).
+This Developer Certificate of Origin (DCO) was adopted on February 26, 2022.
 
-To accept the DCO it is required to put a x between [ ] on `[ ] I accept the DCO` in the PR template when submitting it. The [ ] is an opt-in box, so you have to manually accept it.
+<!-- vale Google.Passive = YES -->
+
+The text of this license is available under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://creativecommons.org/licenses/by-sa/3.0/). It's based on the Linux [Developer Certificate of Origin](http://elinux.org/Developer_Certificate_Of_Origin).
+
+To accept the DCO, put a x between [ ] on `[ ] I accept the Developer Certificate of Origin (DCO)` in the PR template when submitting it. The [ ] is an opt-in box, so you have to manually accept it.
diff --git a/docs/participate/support.md b/docs/participate/support.md
@@ -1,6 +1,6 @@
 # Supporting the project
 
-If you like the project and/or use it, please consider supporting us. It can be done in different ways:
+If you like the project and/or use it, please consider supporting us. You can do this 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,

diff --git a/docs/prerequisites/broker.md b/docs/prerequisites/broker.md
@@ -1,19 +1,19 @@
 # Broker
-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.
+The broker acts as an intermediary between TheengsGateway and your [controller](/prerequisites/controller). Consider it as a centralized hub at the heart of your home automation system. It carries on messages following a publish/subscribe mechanism.
 
 All the events or commands could pass by the broker.
 
 There are many choices of brokers, here are some of the most popular:
-* [Mosquitto](https://mosquitto.org/) (Open source)
-* [Moquette](https://moquette-io.github.io/moquette/) (Open source)
+* [Mosquitto](https://mosquitto.org/) (open source)
+* [Moquette](https://moquette-io.github.io/moquette/) (open source)
 * [HiveMQ](https://www.hivemq.com/hivemq/features/)
-* Embedded MQTT brokers (Home Assistant and OpenHAB)
+* Embedded MQTT brokers (Home Assistant and openHAB)
 
 This [comparison of MQTT implementations](https://en.wikipedia.org/wiki/Comparison_of_MQTT_implementations) on Wikipedia gives you more details about the different choices you have.
 This [list of brokers](https://github.com/mqtt/mqtt.github.io/wiki/brokers) on GitHub seems to be the most exhaustive ones.
 Here is also a [list of criteria for selecting a MQTT broker](https://www.hivemq.com/blog/top-10-mqtt-broker-criteria/) from HiveMQ.
 
-Once your broker is installed, it can be interesting to see the traffic passing to it and to publish data. There are several tools available to do this:
+Once you've installed your broker, it can be interesting to see the traffic passing to it and to publish data. There are several tools available to do this:
 * [MQTT Explorer](http://mqtt-explorer.com/)
 * [HiveMQ MQTT web client](https://github.com/hivemq/hivemq-mqtt-web-client)
 * [MQTT FX](https://mqttfx.jensd.de/)
diff --git a/docs/prerequisites/hardware.md b/docs/prerequisites/hardware.md
@@ -1,6 +1,6 @@
 # Hardware
 
-You can [install](../install/install) Theengs Gateway on various hardware as long as they have a BLE module.
+You can [install](../install/install) Theengs Gateway on various hardware as long as they have a Bluetooth Low Energy (BLE) module.
 
 The project is primarily developed for Linux, with the Raspberry Pi as a reference platform.