Documentation updates for v1.2.0 (#362)

documentation/_toc.yml

@@ -13,6 +13,7 @@ parts:
     chapters:
       - file: core_extensions
       - file: enhanced_integrations
+      - file: helpers
       - file: other_features
 
   - caption: Core extensions
@@ -34,6 +35,7 @@ parts:
       - file: integrations/input_number
       - file: integrations/input_select
       - file: integrations/number
+      - file: integrations/person
       - file: integrations/recorder
       - file: integrations/repairs
       - file: integrations/integration
@@ -42,6 +44,10 @@ parts:
       - file: integrations/switch_as_x
       - file: integrations/zone
 
+  - caption: Helpers
+    chapters:
+      - file: helpers/inverse
+
   # - caption: Tutorials
   #   chapters:
   #     - file: ectoplasms

documentation/enhanced_integrations.md

@@ -4,7 +4,7 @@ title: Enhanced integrations
 subtitle: A little bit of ectoplasm goes a long way. 🧪
 thumbnail: images/social.png
 description: Spook enhances the following Home Assistant integrations by sprinkling some ectoplasmic goodness on top of them.
-date: 2023-08-09T21:29:00+02:00
+date: 2023-09-22T10:47:44+02:00
 ---
 
 Spook enhances the following {term}`Home Assistant` {term}`integrations <integration>` by sprinkling some {term}`ectoplasmic <ectoplasm>` goodness on top of them.
@@ -55,6 +55,11 @@ Spook enhances the following {term}`Home Assistant` {term}`integrations <integra
 [![](https://brands.home-assistant.io/number/icon.png)](integrations/number)
 :::
 
+:::{card} Person
+:footer: 📚 [Learn more](integrations/person)
+[![](https://brands.home-assistant.io/person/icon.png)](integrations/person)
+:::
+
 :::{card} Recorder
 :footer: 📚 [Learn more](integrations/recorder)
 [![](https://brands.home-assistant.io/recorder/icon.png)](integrations/recorder)

documentation/helpers.md

@@ -0,0 +1,19 @@
+---
+subject: Features
+title: Helpers
+subtitle: Although, some people, cannot be helped. 🤷
+date: 2023-09-21T21:29:00+02:00
+---
+
+Spook also provides {term}`helpers <helper>`. The helpers allows you to perform calculations or modifications on existing {term}`entities <entity>` and return the result of that as a new entity.
+
+::::{grid} 1 1 1 1
+
+:::{card} Inverse
+:footer: 📚 [Learn more](helpers/inverse)
+
+Inverts the behavior of a switch or binary sensor entities. On becomes off, and off becomes on. The world is upside down!
+
+:::
+
+::::

documentation/helpers/inverse.md

@@ -0,0 +1,56 @@
+---
+subject: Helpers
+title: Inverse
+subtitle: Stranger Things, the upside down 🙃
+date: 2023-08-21T21:29:00+02:00
+---
+
+The inverse {term}`helper <helper>` allows you to invert the behavior of a {term}`switch <switch>` or {term}`binary sensor <binary sensor>` entity. On becomes off, and off becomes on. The world is upside down!
+
+This can be helpful if you use a switch or binary sensor in a non-standard way, or when the manufacturer of a device has decided to use the opposite logic for the switch or binary sensor (Yeah... they exist... 🤦‍♂️).
+
+It not just inverts the state of the source {term}`entity <entity>`, but also does all {term}`service calls <service call>` in reverse. So if you have an automation call the turn on service on a switch, it will instead call the turn off service on the inverted switch.
+
+## Inverting the behavior of an entity
+
+The inverse helper can be used to invert the behavior of a switch or binary sensor entity.
+
+Don't worry! This is really easy and all fully done via the Home Assistant user interface.
+
+Add one directly to your own instance by selecting the {term}`My Home Assistant` button below:
+
+[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=spook_inverse)
+
+Or add one manually, using the following steps:
+
+1. From the Home Assistant sidebar, select **Settings** and next select **Devices & Services**.
+2. Select the **Helpers** tab.
+3. On the helpers page, in the bottom right corner, select the **+ Create helper** button.
+4. From the list of helpers, select **Inverse 👻**.
+
+```{figure} ../images/helpers/inverse/helper_dialog.png
+:alt: Screenshot of the add helper dialog, which lists the inverse helper.
+:align: center
+```
+
+5. Select the type of entity you want to invert the behavior of.
+
+```{figure} ../images/helpers/inverse/select_entity_type.png
+:alt: Screenshot of the inverse helper dialog, which allows you to select the type of entity to invert.
+:align: center
+```
+
+6. Provide a name for your new inverted entity this helpers provides, and select the entity you want to invert the behavior of in the **Source entity** field.
+7. Turn on **Hide source entity**, if you want to hide the source entity from the Home Assistant interface.
+
+```{figure} ../images/helpers/inverse/configure.png
+:alt: Screenshot of the inverse helper dialog, configuring the new inverted entity.
+:align: center
+```
+
+8. Select **Submit**. Done! 🎉
+
+```{figure} ../images/helpers/inverse/done.png
+:alt: Screenshot showing the newly inverted switch, created with the procedure described above.
+:align: center
+```

documentation/integrations/person.md

@@ -0,0 +1,194 @@
+---
+subject: Enhanced integrations
+title: Person
+subtitle: Now it gets personal 😱
+thumbnail: ../images/integrations/person/example.png
+description: Spook adds some new services to the person integration, which allows you to change device trackers attached to persons in Home Assistant on the fly.
+date: 2023-09-22T10:47:44+02:00
+---
+
+```{image} https://brands.home-assistant.io/person/logo.png
+:alt: The Home Assistant person icon
+:width: 250px
+:align: center
+```
+
+<br><br>
+
+The person {term}`integration <integration>` in {term}`Home Assistant` allows you to track the location of people in your household. It is a collection of device trackers that are grouped together to represent the current location of a person. Additionally, a person may have a user account attached to it, which allows the person to log in to the Home Assistant.
+
+Spook adds some new services to the person {term}`integration <integration>`, that allows you to dynamically change the device trackers attached to a person in Home Assistant.
+
+```{figure} ../images/integrations/person/example.png
+:name: example
+:alt: Screenshot of the developer service tools, listing the new services for persons.
+:align: center
+
+Spook adds some new services to the person integration.
+```
+
+## Devices & entities
+
+Spook does not provide any new devices or entities for this integration.
+
+## Services
+
+Spook adds the following new service to your Home Assistant instance:
+
+### Add a device tracker
+
+Adds a device tracker to a person.
+
+```{figure} ../images/integrations/person/add_device_tracker.png
+:alt: Screenshot of the person add device tracker service call in the developer tools.
+:align: center
+```
+
+```{list-table}
+:header-rows: 1
+* - Service properties
+* - {term}`Service`
+  - Person: Add a device tracker 👻
+* - {term}`Service name`
+  - `person.add_device_tracker`
+* - {term}`Service targets`
+  - No
+* - {term}`Service response`
+  - No response
+* - {term}`Spook's influence`
+  - Newly added service
+* - {term}`Developer tools`
+  - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=person.add_device_tracker)
+    [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=person.add_device_tracker)
+```
+
+```{list-table}
+:header-rows: 2
+* - Service call data
+* - Attribute
+  - Type
+  - Required
+  - Default / Example
+* - `entity_id`
+  - {term}`string <string>`
+  - Yes
+  - `person.frenck`
+* - `device_tracker`
+  - {term}`string <string>` | {term}`list of strings <list>`
+  - Yes
+  - `device_tracker.iphone`
+```
+
+:::{seealso} Example {term}`service call <service call>` in {term}`YAML`
+:class: dropdown
+
+```{code-block} yaml
+:linenos:
+service: person.add_device_tracker
+data:
+    entity_id: person.frenck
+    device_tracker: device_tracker.iphone
+```
+
+To add multiple device trackers at once, use a list:
+
+```{code-block} yaml
+:linenos:
+service: person.add_device_tracker
+data:
+    entity_id: person.frenck
+    device_tracker:
+      - device_tracker.iphone
+      - device_tracker.ipad
+```
+
+:::
+
+### Remove a device tracker
+
+Removes a device tracker from a person.
+
+```{figure} ../images/integrations/person/remove_device_tracker.png
+:alt: Screenshot of the person remove device tracker service call in the developer tools.
+:align: center
+```
+
+```{list-table}
+:header-rows: 1
+* - Service properties
+* - {term}`Service`
+  - Person: Remove a device tracker 👻
+* - {term}`Service name`
+  - `person.remove_device_tracker`
+* - {term}`Service targets`
+  - No
+* - {term}`Service response`
+  - No response
+* - {term}`Spook's influence`
+  - Newly added service
+* - {term}`Developer tools`
+  - [Try this service](https://my.home-assistant.io/redirect/developer_call_service/?service=person.remove_device_tracker)
+    [![Open your Home Assistant instance and show your service developer tools with a specific service selected.](https://my.home-assistant.io/badges/developer_call_service.svg)](https://my.home-assistant.io/redirect/developer_call_service/?service=person.remove_device_tracker)
+```
+
+```{list-table}
+:header-rows: 2
+* - Service call data
+* - Attribute
+  - Type
+  - Required
+  - Default / Example
+* - `entity_id`
+  - {term}`string <string>`
+  - Yes
+  - `person.frenck`
+* - `device_tracker`
+  - {term}`string <string>` | {term}`list of strings <list>`
+  - Yes
+  - `device_tracker.iphone`
+```
+
+:::{seealso} Example {term}`service call <service call>` in {term}`YAML`
+:class: dropdown
+
+```{code-block} yaml
+:linenos:
+service: person.remove_device_tracker
+data:
+    entity_id: person.frenck
+    device_tracker: device_tracker.iphone
+```
+
+To remove multiple device trackers at once, use a list:
+
+```{code-block} yaml
+:linenos:
+service: person.remove_device_tracker
+data:
+    entity_id: person.frenck
+    device_tracker:
+      - device_tracker.iphone
+      - device_tracker.ipad
+```
+
+:::
+
+## Repairs
+
+Spook has no repair detections for this integration.
+
+## Uses cases
+
+Some use cases for the enhancements Spook provides for this integration:
+
+- Adding/removing temporary device trackers that represent a location of a person. For example, if you have a tracker in a car, you could temporary attach it to a person if you know that person took that car.
+
+## Blueprints & tutorials
+
+There are currently no known {term}`blueprints <blueprint>` or tutorials for the enhancements Spook provides for this integration. If you created one or stumbled upon one, [please let us know in our discussion forums](https://github.com/frenck/spook/discussions).
+
+## Features requests, ideas and support
+
+If you have an idea on how to further enhance this integration, for example, by adding a new service, entity, or repairs detection; feel free to [let us know in our discussion forums](https://github.com/frenck/spook/discussions).
+
+Are you stuck using these new features? Or maybe you've run into a bug? Please check the [](../support) page on where to go for help.

documentation/support.md

@@ -4,7 +4,7 @@ title: Support
 subtitle: Getting directions in this rollercoaster theme park. 🎢
 thumbnail: /images/support.png
 description: Spook is not supported by the Home Assistant project, however, there are still quite a few places where you can get help. This place guides you to the right place.
-date: 2023-08-09T21:29:00+02:00
+date: 2023-09-22T10:38:47+02:00
 ---
 
 Spook is provided as-is, without any warranty or any real support, and above all: Is absolutely **unsupported** by the {term}`Home Assistant` project. However, if you run into issues, where should you go?
@@ -22,6 +22,11 @@ Spook is provided as-is, without any warranty or any real support, and above all
 - [The Home Assistant Reddit](https://www.reddit.com/r/homeassistant/)
 - [The Home Assistant Facebook group](https://www.facebook.com/groups/homeassistant/)
 
+There are also some language-specific communities:
+
+- [Dutch Domotics Discord chat server](https://discord.gg/Ee5X7T7)
+- [Communauté Francophone Discord chat server](https://discord.hacf.fr/)
+
 ## I'm sure I've found a bug!
 
 Great! 🎉 Well, not really, but at least it means we can look into fixing it, so others won't experience the same issue.