Docs soft launch (#578)

* Initial MkDocs

* Docs

* Update docs

* Added discovery info

* Update docs

* WIP

* WIP

* Add legacy images

.github/ISSUE_TEMPLATE/bug.yml

@@ -16,9 +16,9 @@ body:
   attributes:
     label: Checklist
     options:
-      - label: I have added `battery_notes:` to my configuration.yaml and restarted. 
+      - label: I have added `battery_notes:` to my configuration.yaml and restarted.
         required: true
-      - label: I have read the [FAQ's](https://github.com/andrew-codechimp/HA-Battery-Notes#faqs). 
+      - label: I have read the [FAQ's](https://github.com/andrew-codechimp/HA-Battery-Notes#faqs).
         required: true
       - label: I have enabled debug logging for my installation.
         required: true
@@ -56,4 +56,4 @@ body:
 - type: textarea
   attributes:
     label: "Diagnostics dump"
-    description: "Drag the diagnostics dump file here. (see https://www.home-assistant.io/integrations/diagnostics/ for info)"
+    description: "Drag the diagnostics dump file here. (see https://www.home-assistant.io/integrations/diagnostics/ for info)"

.github/workflows/deploy_docs.yml

@@ -0,0 +1,28 @@
+name: Deploy docs
+on:
+  push:
+    paths:
+      - 'mkdocs.yml'
+      - 'docs/**'
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy_docs:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.github/workflows/validate.yml

@@ -9,8 +9,10 @@ on:
       - "main"
     paths-ignore:
       - 'custom_components/battery_notes/data/**'
+      - 'docs/**'
       - 'README.md'
       - 'library.md'
+      - 'mkdocs.yml'
   pull_request:
     branches:
       - "main"

README.md

@@ -178,4 +178,3 @@ Thanks to everyone who has submitted devices to the library.
 [releases-shield]: https://img.shields.io/github/release/andrew-codechimp/HA-Battery-Notes.svg?style=for-the-badge
 [releases]: https://github.com/andrew-codechimp/HA-Battery-Notes/releases
 [download-latest-shield]: https://img.shields.io/github/downloads/andrew-codechimp/ha-battery-notes/latest/total?style=for-the-badge
-

docs/community.md

@@ -0,0 +1,7 @@
+# Community Contributions
+
+These are a few contributions by the community.
+
+## Coming soon
+
+If you want to contribute then fork, edit this page and submit a pull request.

docs/configuration.md

@@ -0,0 +1,40 @@
+# Configuration
+
+You can add these options to change the default behaviour of Battery Notes by adding them to your Home Assistant configuration.yaml under the battery_notes: property, like so:
+
+```
+battery_notes:
+  enable_autodiscovery: true
+  show_all_devices: false
+  enable_replaced: true
+```
+
+A restart of Home Assistant is required for the changed to take effect.
+
+Name | Type | Requirement | Default | Description |
+-- | -- | -- | -- | -- |
+enable_autodiscovery | Boolean | Optional | True | If set to true will automatically match devices against the library and create a setup flow within the integrations page. |
+show_all_devices | Boolean | Optional | False | If set to true will show all devices in the manual add dropdown, rather than just those with batteries. |
+enable_replaced | Boolean | Optional | True | If set to false new devices added to battery notes will have the battery replaced sensor and button disabled.  Any devices you have previously added to Battery Notes you will have to disable these sensors manually, which also means you can enable specific sensors of important ones you want to track. |
+user_library | String | Optional |  | If specified then a user library file will be searched prior to the main library, the user library must be in the same format as the library and placed in the same folder. Only really used for dev purposes. |
+
+# Debug Logging
+
+To analyse issues on your installation it might be helpful to enable debug logging.
+
+You can enable debug logging by going to the Battery Notes integration page. You can use the button below.
+
+[![Open your Home Assistant instance and show Battery Notes.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integration/?domain=battery_notes)
+
+Next click `Enable debug logging`
+
+**Alternatively**
+
+Add the following to configuration.yaml:
+
+```
+    logger:
+      default: warning
+      logs:
+        custom_components.battery_notes: debug
+```

docs/entities.md

@@ -0,0 +1,24 @@
+# Entities
+
+You'll get the following entities for each device you have added to battery notes.
+
+## Battery Type
+`sensor.{{device_name}}_battery_type`
+
+The battery quantity and type display in an easy to use single entity.  The quantity is only shown if more than 1.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `battery_quantity` | `int` | The quantity of batteries |
+| `battery_type` | `string` | The type of batteries |
+
+## Battery Last Replaced
+`sensor.{{device_name}}_battery_last_replaced`
+
+The last time the battery of the device was replaced.
+
+## Battery Replaced
+`button.{{device_name}}_battery_replaced`
+
+A button to set the battery_last_replaced entity to now.
+

docs/faq.md

@@ -0,0 +1,44 @@
+# FAQ
+
+* Does a device have to be in the library?  
+No, you can always add a device manually by going to Settings -> Integrations -> Battery Notes screen add a new device where you can enter the battery details manually.
+
+* Why is my device not being discovered?  
+It could be missing from the [library](https://github.com/andrew-codechimp/HA-Battery-Notes/blob/main/library.md) or does not exactly match the name that your integration has.  ZHA and Z2M for example have different manufacturers/models for the same device, you can still add it manually or contribute to the library.
+
+* When is the library updated?  
+It updates when Home Assistant is restarted and approximately every 24 hours after that.  
+It will pull the latest devices that have been merged into the main branch, if you have recently submitted a pull request for a new device it will not appear until it has been manually reviewed and merged.
+
+* How do I remove a battery note on a device?  
+Go into the Settings -> Integrations -> Battery Notes, use the menu on the right of a device and select Delete, this will only delete the battery note, not the whole device.
+
+* Why does the device icon change?  
+Unfortunately where there are multiple integrations associated with a device Home Assistant seems to choose an icon at random, I have no control over this.
+
+* Can I edit a battery note?  
+Go into Settings -> Integrations -> Battery Notes and click Configure on the device you want to edit.
+
+* Why am I only able to see some of my devices when adding manually?  
+By default Battery Notes filters the device list to only devices with a battery, if you want to add a battery note to a random device then you can disable this filtering by adding the following configuration to your `configuration.yaml` and restart Home Assistant to see all devices.
+```
+battery_notes:
+  show_all_devices: True
+```
+
+* I only want to add notes to a few devices, can I disable auto discovery?  
+If you want to disable this functionality you can add the following to your `configuration.yaml`, after a restart of Home Assistant you will not see discovered battery notes.
+```
+battery_notes:
+  enable_autodiscovery: False
+```
+
+* I don't want to track battery replacement, can I disable this?  
+Yes, you can add the following to your `configuration.yaml`, after a restart of Home Assistant *new* devices added to battery notes will have the battery replaced sensor and button disabled.  Any devices you have previously added to Battery Notes you will have to disable/enable these sensors manually, which also means you can just enable specific sensors of important ones you want to track.
+```
+battery_notes:
+  enable_replaced: False
+```
+
+* How can I show my support?  
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/codechimp)

docs/index.md

@@ -0,0 +1,45 @@
+# Battery Notes for Home Assistant
+
+Integration to add battery notes to a device, with automatic discovery via a growing [battery library](https://github.com/andrew-codechimp/HA-Battery-Notes/blob/main/library.md) for devices.  
+Track both the battery type and also when the battery was replaced.  
+
+*Please star this repo on [GitHub](https://github.com/andrew-codechimp/HA-Battery-Notes) if you find it useful*  
+*If you want to show your support please*
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/codechimp)
+
+
+## Features
+
+The integration will add additional diagnostic entities to your device.
+
+![device example](./assets/screenshot-device.png)
+
+* [Entities](./entities.md)
+* [Services](./services.md)
+
+## How to use Battery Notes
+Once you have [installed the integration](https://github.com/andrew-codechimp/HA-Battery-Notes#installation) you will hopefully have some devices discovered and you can follow the Notification to confirm their details and add them, if you don't have devices discovered you can add them manually.
+
+![device discovery](./assets/screenshot-discovery.png)
+
+## To add a battery note manually
+* Go to Settings/Integrations and click Add Integration.
+* Select Battery Notes.
+* Choose your device from the drop down and click next.
+* Enter the battery type and quantity and click submit.
+
+!!! info
+
+    The library is updated automatically with new devices approximately every 24 hours from starting Home Assistant, if you have added a device to the library using [this form](https://github.com/andrew-codechimp/HA-Battery-Notes/issues/new?template=new_device_request.yml&title=[Device]%3A+) then this will take about a day to be discovered once it's approved and added.
+
+
+## Community Contributions
+
+A collection of community contributions can be found on the [community contributions](./community.md) page. 
+
+
+## FAQ
+
+Before raising anything, please read through the [faq](./faq.md). If you have questions, then you can raise a [discussion](https://github.com/andrew-codechimp/HA-Battery-Notes/discussions). If you have found a bug or have a feature request please [raise it](https://github.com/andrew-codechimp/HA-Battery-Notes/issues) using the appropriate report template.
+

docs/library.md

@@ -0,0 +1,38 @@
+# Library
+
+The library contains user contributed device definitions to allow discovery of the most popular devices.  
+The library is updated when Home Assistant is restarted and approximately every 24 hours after that.  
+It will pull the latest devices that have been merged into the main branch, if you have recently submitted a pull request for a new device it will not appear until it has been manually reviewed and merged.
+
+# Contributing to the library
+
+## Submit Definition via GitHub Issues Form
+
+To add a new device via GitHub Issues, fill out [this form](https://github.com/andrew-codechimp/HA-Battery-Notes/issues/new?template=new_device_request.yml&title=[Device]%3A+).  
+Upon submission of the issue, GitHub will attempt to make the required code changes automatically.
+
+## Submit Definition via Pull Request
+
+Fork the repository, add your device details to the JSON document `custom_components/battery_notes/data/library.json`, and then submit a pull request. Do not enable GitHub Actions (disabled by default) as this will mess with the pull request and are unnecessary for a library submission.
+
+* The manufacturer and model should be exactly what is displayed on the Device screen within Home Assistant.
+* The make & model names may be different between integrations such as Zigbee2MQTT and ZHA, if you see a similar device please duplicate the entry rather than changing it.
+* Please keep devices in alphabetical order by manufacturer/model.
+* The `battery_quantity` data is numeric (no quotes) and optional. If a device only requires a single battery, it should be omitted.
+* The `battery_type` data should follow the most common naming for general batteries (ex. AAA, D) and the IEC naming for battery cells according to [Wikipedia](https://en.wikipedia.org/wiki/List_of_battery_sizes) (ex. CR2032, 18650)
+* If a device has a bespoke rechargeable battery you can use `"battery_type": "Rechargeable"`
+* For devices like smoke alarms where the battery is not replaceable you can use `"battery_type": "Irreplaceable"`
+* If a device shouldn't be discovered because there are multiple revisions with the same model number but different battery types it can be added to the library with a `"battery_type": "MANUAL"` to note it is a device that shouldn't have a battery definition added to the library to save removal/re-add because people don't realise there are variants.
+
+For the example image below, your JSON entry will look like this:
+
+```
+{
+    "manufacturer": "Philips",
+    "model": "Hue motion sensor (9290012607)",
+    "battery_type": "AAA",
+    "battery_quantity": 2
+},
+```
+
+![device details](./assets/screenshot-device-info.png)

docs/services.md

@@ -0,0 +1,10 @@
+# Services
+
+## battery_notes.set_battery_replaced
+
+For updating the [battery replaced date](./entities.md#battery-replaced). This allows you to change the date a battery was replaced.
+
+| Parameter                | Optional | Description                                                                                                           |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `data.device_id`      | `no`    | The device id that you want to change the battery replaced date for. |
+| `data.datetime_replaced` | `yes`    | The optional datetime that you want to set the battery replaced to, if omitted the current date/time will be used. |

mkdocs.yml

@@ -0,0 +1,43 @@
+site_name: Battery Notes for Home Assistant
+site_url: https://andrew-codechimp.github.io/ha-battery-notes
+repo_url: https://github.com/andrew-codechimp/ha-battery-notes
+docs_dir: docs
+
+nav:
+  - Home: index.md
+  - Entities: entities.md
+  - Services: services.md
+  - Library: library.md
+  - Configuration: configuration.md
+  - Community: community.md
+  - FAQ: faq.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - attr_list
+  - toc:
+      permalink: "#"
+
+theme:
+  name: material
+  features:
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - toc.follow
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: light blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: light blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode