From cae42c9fe3940f63102666768abd89301c99f6c5 Mon Sep 17 00:00:00 2001
From: Paulus Schoutsen <balloob@gmail.com>
Date: Mon, 9 Jan 2023 10:22:51 -0500
Subject: [PATCH] Tweaks to intent docs (#1618)

* Tweaks to intent docs

* Move to core section

* Update docs/intent_firing.md
---
 docs/intent_conversation.md | 19 -------------------
 docs/intent_firing.md       | 19 ++++++++++++++++++-
 docs/intent_handling.md     |  4 ++--
 sidebars.js                 | 21 ++++++++++-----------
 4 files changed, 30 insertions(+), 33 deletions(-)
 delete mode 100644 docs/intent_conversation.md

diff --git a/docs/intent_conversation.md b/docs/intent_conversation.md
deleted file mode 100644
index 14c44222..00000000
--- a/docs/intent_conversation.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-title: "Registering sentences"
----
-
-The conversation component handles incoming commands from the frontend and converts them to intents. It does this based on registered sentences.
-
-As a component, you can register sentences with the conversation component to allow it to be remote controlled. Refer to named slots by putting the slot name between curly braces: `{item}`. Use square brackets around (partial) words to mark them as optional.
-
-Example code:
-
-```python
-async def async_setup(hass, config):
-    hass.components.conversation.async_register(
-        "MyCoolIntent",
-        ["I think that {object} is [very] cool", "Nothing is cooler than {object}"],
-    )
-```
-
-If a sentence like "I think that beer is cool" comes in, the conversation component will generate an intent of type `MyCoolIntent` and with 1 slot, named `object` and value `beer`.
diff --git a/docs/intent_firing.md b/docs/intent_firing.md
index efdf2be2..f2dcfb17 100644
--- a/docs/intent_firing.md
+++ b/docs/intent_firing.md
@@ -2,7 +2,24 @@
 title: "Firing intents"
 ---
 
-When you fire an intent, you will get a response back or an error will be raised. It is up to the component to return the result to the user.
+If your code matches the user's speech or text to intents, you can let the intent be handled by Home Assistant. This can be done from inside your own integration, or via the generic Intent handle API.
+
+When you fire an intent, you will get a response back or an error will be raised. It is up to your code to return the result to the user.
+
+## HTTP API
+
+When the intent integration is loaded, an HTTP API endpoint is available at `/api/intent/handle`. You can POST JSON data to it containing an intent name and it's data:
+
+```json
+{
+  "name": "HassTurnOn",
+  "data": {
+    "name": "Kitchen Light"
+  }
+}
+```
+
+## Home Assistant integration
 
 Example code to handle an intent in Home Assistant.
 
diff --git a/docs/intent_handling.md b/docs/intent_handling.md
index 7a84f698..f16e8f8d 100644
--- a/docs/intent_handling.md
+++ b/docs/intent_handling.md
@@ -7,7 +7,6 @@ Any component can register to handle intents. This allows a single component to
 A component has to register an intent handler for each type that it wants to handle. Intent handlers have to extend `homeassistant.helpers.intent.IntentHandler`
 
 ```python
-import asyncio
 from homeassistant.helpers import intent
 
 DATA_KEY = "example_key"
@@ -32,10 +31,11 @@ class CountInvocationIntent(intent.IntentHandler):
     async def async_handle(self, intent_obj):
         """Handle the intent."""
         intent_obj.hass.data[DATA_KEY] += 1
+        count = intent_obj.hass.data[DATA_KEY]
 
         response = intent_obj.create_response()
         response.async_set_speech(
-            f"This intent has been invoked {intent_obj.hass.data[DATA_KEY]} times"
+            f"This intent has been invoked {count} times"
         )
         return response
 ```
diff --git a/sidebars.js b/sidebars.js
index 454a9f16..dd0de2e9 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -88,7 +88,7 @@ module.exports = {
     "operating-system/debugging",
     "operating-system/partition",
     "operating-system/board-metadata",
-    "operating-system/deployment"
+    "operating-system/deployment",
   ],
   Supervisor: ["supervisor", "supervisor/development", "supervisor/debugging"],
   // Old structure, still to move/migrate
@@ -122,7 +122,7 @@ module.exports = {
       "development_guidelines",
       "development_testing",
       "development_catching_up",
-      "development_tips"
+      "development_tips",
     ],
     "Building Integrations": [
       "creating_component_index",
@@ -157,14 +157,14 @@ module.exports = {
     Entities: [
       "core/entity",
       {
-        type: 'autogenerated',
-        dirName: 'core/entity',
+        type: "autogenerated",
+        dirName: "core/entity",
       },
     ],
     Platforms: [
       {
-        type: 'autogenerated',
-        dirName: 'core/platform',
+        type: "autogenerated",
+        dirName: "core/platform",
       },
     ],
     Registries: [
@@ -180,18 +180,17 @@ module.exports = {
       "device_automation_condition",
       "device_automation_action",
     ],
-    Misc: ["development_validation", "development_typing", "instance_url"],
-  },
-  Misc: {
-    Introduction: ["misc"],
     Intents: [
       "intent_index",
       "intent_firing",
       "intent_handling",
-      "intent_conversation",
       "intent_builtin",
       "intent_conversation_api",
     ],
+    Misc: ["development_validation", "development_typing", "instance_url"],
+  },
+  Misc: {
+    Introduction: ["misc"],
     "Building a Python library": [
       "api_lib_index",
       "api_lib_auth",