[CI] Run Vale in pre-commit to spellcheck documentation (#210)

theengs · Jan 5, 2024 · 9c98635 · 9c98635
1 parent f32fd27
commit 9c98635
Show file tree

Hide file tree

Showing 10 changed files with 69 additions and 22 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -4,6 +4,24 @@ on:
   pull_request:
 
 jobs:
+  docs:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Vale
+        uses: pre-commit/[email protected]
+        with:
+          extra_args: vale
+  format:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Ruff format
+        uses: pre-commit/[email protected]
+        with:
+          extra_args: ruff-format
   test:
     strategy:
       fail-fast: false
@@ -23,8 +41,14 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
-      - name: Run pre-commit
+      - name: Ruff
         uses: pre-commit/[email protected]
+        with:
+          extra_args: ruff
+      - name: Mypy
+        uses: pre-commit/[email protected]
+        with:
+          extra_args: mypy
       - name: Install requirements
         run: |
           pip3 install --upgrade pip

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,5 +1,9 @@
 ---
 repos:
+- repo: https://github.com/errata-ai/vale
+  rev: 'v2.30.0'
+  hooks:
+    - id: vale
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: 'v0.1.9'
   hooks:

diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,5 @@
+StylesPath = "vale/styles"
+MinAlertLevel = error
+Vocab = Theengs
+[*.md]
+BasedOnStyles = Vale
diff --git a/README.md b/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.
 
-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 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 component 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.
 
-The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, QingPing, ThermoBeacon, ClearGrass, Blue Maestro and many more.
+The gateway will retrieve 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)
 
@@ -40,7 +40,7 @@ Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories
 5. Start the Add-on.
 
 ## Install Theengs Gateway as a snap
-Theengs Gateway is also packaged as a snap in the [Snap Store](https://snapcraft.io/theengs-gateway). If you have snapd running on your Linux distribution, which is the case by default on Ubuntu, you can install the Theengs Gateway snap as:
+Theengs Gateway is also packaged as a snap in the [Snap Store](https://snapcraft.io/theengs-gateway). If you have `snapd` running on your Linux distribution, which is the case by default on Ubuntu, you can install the Theengs Gateway snap as:
 
 [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/theengs-gateway)
 

diff --git a/docs/README.md b/docs/README.md
@@ -6,12 +6,12 @@ title: 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.
 
-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 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 component 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.
 
-The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, QingPing, ThermoBeacon, ClearGrass, Blue Maestro and many more.
+The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more.
diff --git a/docs/install/install.md b/docs/install/install.md
@@ -35,7 +35,7 @@ Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories
 5. Start the Add-on.
 
 ## Install Theengs Gateway as a snap
-Theengs Gateway is also packaged as a snap in the [Snap Store](https://snapcraft.io/theengs-gateway). If you have snapd running on your Linux distribution, which is the case by default on Ubuntu, you can install the Theengs Gateway snap as:
+Theengs Gateway is also packaged as a snap in the [Snap Store](https://snapcraft.io/theengs-gateway). If you have `snapd` running on your Linux distribution, which is the case by default on Ubuntu, you can install the Theengs Gateway snap as:
 
 [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-white.svg)](https://snapcraft.io/theengs-gateway)
 

diff --git a/docs/participate/development.md b/docs/participate/development.md
@@ -4,7 +4,7 @@ We like pull requests from everyone. By participating in this project, you
 agree to follow the [code of conduct](https://github.com/theengs/gateway/blob/master/CODE_OF_CONDUCT.md).
 
 * We use the [pre-commit](https://pre-commit.com) system to identify simple issues before submission to code review. Install it with `pip install pre-commit`.
-* Fork the [development branch](https://github.com/theengs/gateway/tree/development), then clone the repo.
+* Fork the [development branch](https://github.com/theengs/gateway/tree/development), then clone the repository.
 * Run `pre-commit install` to set up the Git hook scripts.
 * Make your modification.
 * Review your code, build it.

diff --git a/docs/prerequisites/broker.md b/docs/prerequisites/broker.md
@@ -9,12 +9,11 @@ There are many choices of brokers, here are some of the most popular:
 * [HiveMQ](https://www.hivemq.com/hivemq/features/)
 * Embedded MQTT brokers (Home Assistant and OpenHAB)
 
-This [wikipedia list](https://en.wikipedia.org/wiki/Comparison_of_MQTT_implementations) gives you more details about the different choices you have.
-This [github list](https://github.com/mqtt/mqtt.github.io/wiki/libraries) seems to be the most exhaustive ones.
-Here is also some [ideas of criteria](https://www.hivemq.com/blog/top-10-mqtt-broker-criteria/) from HiveMQ.
+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, so as to do that there are several tools available:
+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:
 * [MQTT Explorer](http://mqtt-explorer.com/)
-* [HIVE MQ Web client](https://github.com/hivemq/hivemq-mqtt-web-client)
+* [HiveMQ MQTT web client](https://github.com/hivemq/hivemq-mqtt-web-client)
 * [MQTT FX](https://mqttfx.jensd.de/)
-
diff --git a/docs/use/use.md b/docs/use/use.md
@@ -19,13 +19,13 @@ docker run --rm \
 ```
 
 :::tip
-If your mqtt broker is installed on the same instance as the gateway you can use `localhost` as the `<mqtt_broker_host_ip>`.
+If your MQTT broker is installed on the same instance as the gateway you can use `localhost` as the `<mqtt_broker_host_ip>`.
 :::
 
 ### Checking the data published by the gateway
 Once the command launched you should see MQTT payloads appearing on the broker. To visualize these data you have to use an [MQTT client tool](../prerequisites/broker).
 
-![mqtt](../img/TheengsGateway_mqtt_explorer.png)
+![MQTT](../img/TheengsGateway_mqtt_explorer.png)
 
 Example payload received:
 ```json
@@ -182,7 +182,7 @@ If possible, the data will be decoded and published.
 [OpenMQTTGateway](https://docs.openmqttgateway.com/), proposes a [web upload](https://docs.openmqttgateway.com/upload/web-install.html) binary `esp32dev-ble-mqtt-undecoded` that will publish directly to 'home/<gateway name>/BTtoMQTT` making it directly compatible with Theengs Gateway MQTTtoMQTT decoding feature.
 
 :::tip
-By default Theengs Gateway will listen to `home/+/BTtoMQTT/undecoded`, if you have several ESP32 gateways with OpenMQTTGateway undecoded, Theengs will pickup all of them and centralize the decoded BT sensor data in one place.
+By default Theengs Gateway will listen to `home/+/BTtoMQTT/undecoded`, if you have several ESP32 gateways with OpenMQTTGateway sending out MQTT messages with undecoded data, Theengs will pickup all of them and centralize the decoded BT sensor data in one place.
 :::
 
 ## Home Assistant auto discovery
@@ -191,14 +191,14 @@ If enabled (default), decoded devices will publish their configuration to Home A
 - If you want to use Home Assistant discovery with other home automation gateways such as openHAB, set `-Dh` or `--hass_discovery` to 0 (disable).
 - The discovery topic can be set with the `-Dt` or `--discovery_topic` command line argument.
 - The discovery name can be set wit the `-Dn` or `--discovery_name` command line argument.
-- Devices can be filtered from discovery with the `-Df` or `--discovery_filter` argument which takes a list of device "model_id" to be filtered.
+- Devices can be filtered from discovery with the `-Df` or `--discovery_filter` argument which takes a list of device model ID to be filtered.
 
 The `IBEACON` and random MAC devices (APPLE, MS-CDP and GAEN) are not discovered as their addresses (IDs) change over time resulting in multiple discoveries.
 
 ## Passive scanning
 Passive scanning (`-s passive` or `--scanning_mode passive`) only works on Windows or Linux kernel >= 5.10 and BlueZ >= 5.56 with experimental features enabled.
 
-To enable experimental features in BlueZ on a Linux distribution that uses systemd, run the following command:
+To enable experimental features in BlueZ on a Linux distribution that uses `systemd`, run the following command:
 
 ```shell
 sudo systemctl edit bluetooth.service
@@ -213,7 +213,7 @@ ExecStart=/usr/lib/bluetooth/bluetoothd --experimental
 ```
 
 :::tip
-On other linux variants the path might be slightly different. This can usually be seen by the commented out entries of `ExecStart=…` when editing bluetooth.service or with the `which bluetoothd` command.
+On other Linux variants the path might be slightly different. This can usually be seen by the commented out entries of `ExecStart=…` when editing bluetooth.service or with the `which bluetoothd` command.
 :::
 
 Save and close the file and then run the following commands:

diff --git a/vale/styles/Vocab/Theengs/accept.txt b/vale/styles/Vocab/Theengs/accept.txt
@@ -0,0 +1,15 @@
+bindkey
+Domoticz
+Govee
+Inkbird
+iBeacon
+iCloud
+ioBroker
+Jeedom
+Mosquitto
+Python
+Qingping
+Theengs
+undecoded
+Unported
+Xiaomi