From 1c85deccf654a72ec37f7268687b234db7a16c6c Mon Sep 17 00:00:00 2001 From: Joe Block Date: Sun, 5 Mar 2023 09:47:46 -0700 Subject: [PATCH 1/4] Update TOC Signed-off-by: Joe Block --- README.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 432eea8..f3d5e8c 100644 --- a/README.md +++ b/README.md @@ -14,21 +14,22 @@ Using MQTT discoverable devices lets us add new sensors and devices to HA withou ## Table of Contents -- [ha-mqtt-discoverable](#ha-mqtt-discoverable) - - [Installing](#installing) - - [Python](#python) - - [Docker](#docker) - - [Supported entities](#supported-entities) - - [Binary sensor](#binary-sensor) - - [Usage](#usage) - - [Device](#device) - - [Usage](#usage-1) - - [Contributing](#contributing) - - [Scripts Provided](#scripts-provided) - - [`hmd`](#hmd) - - [`hmd create binary sensor`](#hmd-create-binary-sensor) - - [`hmd create device`](#hmd-create-device) - - [Contributors](#contributors) +- [Installing](#installing) + - [Python](#python) + - [Docker](#docker) +- [Supported entities](#supported-entities) + - [Binary sensor](#binary-sensor) + - [Usage](#usage) + - [Switch](#switch) + - [Usage](#usage-1) +- [Device](#device) + - [Usage](#usage-2) +- [Contributing](#contributing) +- [Scripts Provided](#scripts-provided) + - [`hmd`](#hmd) + - [`hmd create binary sensor`](#hmd-create-binary-sensor) + - [`hmd create device`](#hmd-create-device) +- [Contributors](#contributors) From 71c15e99e11bdb3cfe7b34c8714a4bc8d492270e Mon Sep 17 00:00:00 2001 From: Joe Block Date: Sun, 5 Mar 2023 09:48:09 -0700 Subject: [PATCH 2/4] Update contributing guidelines - Formalize use of Google-style docstrings - Update pre-commit documentation Signed-off-by: Joe Block --- Contributing.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Contributing.md b/Contributing.md index 2f06f0d..1e0f8f8 100644 --- a/Contributing.md +++ b/Contributing.md @@ -2,15 +2,16 @@ ## Setup -ha-mqtt-discovery uses [poetry](https://python-poetry.org/) to manage module dependencies and make packaging the module easier. Once you install `poetry`, run `poetry install` to have it create a venv for you to use during development. +`ha-mqtt-discovery` uses [poetry](https://python-poetry.org/) to manage module dependencies and make packaging the module easier. Once you install `poetry`, run `poetry install` to have it create a venv for you to use during development. -We use [pre-commit](https://pre-commit.com/) to run our pre-commit/postcheckout etc `git` hooks. Please run `pre-commit install` at the root of the repository to enable automatic handling of the `git` pre-commit scripts. This won't affect any of your other repositories, just this one. The pre-commit scripts run `black` on the `.py` files that you are committing. Their configuration is managed in the file `.pre-commit-config.yaml`. +We use [pre-commit](https://pre-commit.com/) to run our pre-commit/postcheckout etc `git` hooks. Please run `pre-commit install` at the root of the repository to enable automatic handling of the `git` pre-commit scripts. This won't affect any of your other repositories, just this one. The pre-commit scripts run `black` on the `.py` files that you are committing along with some other checks (preventing accidental large file additions, merge conflict checks, whitespace trimming, etc). Their configuration is managed in [.pre-commit-config.yaml](https://github.com/unixorn/ha-mqtt-discovery/blob/main/.pre-commit-config.yaml. ## Contribution Guidelines -- PRs should include readme updates for any added/changed/removed functionality. +- PRs should include readme updates with code examples for any added/changed/removed functionality. - The current state of tests in the repo is frankly terrible. [issues/20](https://github.com/unixorn/ha-mqtt-discovery/issues/20) to backfill tests is already going to be a lot of work, so please add pytest tests for any new functions you add to keep from piling on more. - Please use `pydantic` to validate input settings and provide default values. +- Please use Google-style docstrings - see their [style guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) for details. ## Linting the project files From afeb5b93fb487ff4d77fcf48f5284aa80f0865e5 Mon Sep 17 00:00:00 2001 From: Joe Block Date: Sun, 5 Mar 2023 09:53:59 -0700 Subject: [PATCH 3/4] Update PR template Signed-off-by: Joe Block --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5f38b40..6fe5c31 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,7 +24,7 @@ -- [ ] I have read the **CONTRIBUTING** document. +- [ ] I have read the [CONTRIBUTING](https://github.com/unixorn/ha-mqtt-discovery/blob/main/Contributing.md) document. - [ ] All new and existing tests pass. - [ ] Any scripts added use `#!/usr/bin/env interpreter` instead of potentially platform-specific direct paths (`#!/bin/sh` is an allowed exception) - [ ] Scripts added/updated in this PR are all marked executable. From 5c380891359c9741f2846be85570dbd742ca5fd9 Mon Sep 17 00:00:00 2001 From: Joe Block Date: Sun, 5 Mar 2023 09:58:30 -0700 Subject: [PATCH 4/4] Markdownlint corrections Signed-off-by: Joe Block --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f3d5e8c..3e44231 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ +# ha-mqtt-discoverable + [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![License](https://img.shields.io/github/license/unixorn/ha-mqtt-discover.svg)](https://opensource.org/license/apache-2-0/) [![GitHub last commit (branch)](https://img.shields.io/github/last-commit/unixorn/ha-mqtt-discovery/main.svg)](https://github.com/unixorn/ha-mqtt-discovery) [![Downloads](https://static.pepy.tech/badge/ha-mqtt-discoverable)](https://pepy.tech/project/ha-mqtt-discoverable) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) -# ha-mqtt-discoverable - A python 3 module that takes advantage of Home Assistant's MQTT discovery protocol to create sensors without having to define anything on the HA side. Using MQTT discoverable devices lets us add new sensors and devices to HA without having to restart HA. This module includes scripts to make it easy to create discoverable devices from the command line if you don't want to bother writing python. @@ -43,7 +43,9 @@ ha-mqtt-discoverable runs on Python 3.10 or later. ### Docker -If you only need to use the command line tools, the simplest way is to use them with `docker` or `nerdctl`. It won't interfere with your system python and potentially cause you issues there. You can use the [unixorn/ha-mqtt-discoverable](https://hub.docker.com/repository/docker/unixorn/ha-mqtt-discoverable) image on dockerhub directly, but if you add `$reporoot/bin` to your `$PATH`, the `hmd` script in there will automatically run the command line tools inside a docker container with `docker` or `nerdctl`, depending on what it finds in your `$PATH`. +If you only need to use the command line tools, the simplest way is to use them with `docker` or `nerdctl`. It won't interfere with your system python and potentially cause you issues there. + +You can use the [unixorn/ha-mqtt-discoverable](https://hub.docker.com/repository/docker/unixorn/ha-mqtt-discoverable) image on dockerhub directly, but if you add `$reporoot/bin` to your `$PATH`, the `hmd` script there will automatically run the command line tools inside a docker container with `docker` or `nerdctl`, depending on what it finds in your `$PATH`. ## Supported entities