Merge pull request #49 from unixorn/update-contributing-guidelines

Update contributing guidelines

.github/PULL_REQUEST_TEMPLATE.md

@@ -24,7 +24,7 @@
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. [x] -->
 <!--- If you're unsure about any of these, don't hesitate to ask. I'm happy to help! -->
 
-- [ ] 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.

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
 

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.
@@ -14,21 +14,22 @@ Using MQTT discoverable devices lets us add new sensors and devices to HA withou
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## 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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -42,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