From 0eb93417d2d6836376fe263ee6fbf47f7346b048 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Thu, 27 Feb 2025 10:58:22 +0100
Subject: [PATCH] about integration docs: improve page (#2582)
* about integration docs: improve page
- add screenshots showing the configuration variables blocks
- add image titles
- style tweaks
* Fix typo
* Fix title
* Specify installation
---
docs/documenting/integration-docs-examples.md | 123 +++++++++++++-----
1 file changed, 93 insertions(+), 30 deletions(-)
diff --git a/docs/documenting/integration-docs-examples.md b/docs/documenting/integration-docs-examples.md
index bf1e0efd..0208ea36 100644
--- a/docs/documenting/integration-docs-examples.md
+++ b/docs/documenting/integration-docs-examples.md
@@ -6,7 +6,7 @@ This page shows examples of the available documentation features (such as inline
Use this template together with the following documentation:
-- The integration documentation template on under [/_integrations/_integration_docs_template.markdown](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/_integration_docs_template.markdown).
+- The integration documentation template in the home-assistant.io repository under [/_integrations/_integration_docs_template.markdown](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/_integration_docs_template.markdown).
- [Documentation standard](https://developers.home-assistant.io/docs/documenting/standards).
- The documentation rules of the [Integration Quality Scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/).
@@ -16,16 +16,19 @@ This section shows elements you can use within your text.
### My links
-To indicate a location in the UI, you can use a [My link](https://www.home-assistant.io/docs/tools/quick-bar/#my-links). If the reader selects that link, that page opens in their installation. For example: `"Go to {% my integrations title="**Settings** > **Devices & services**" %} and select your integration."`
+To indicate a location in the UI, you can use a [My link](https://www.home-assistant.io/docs/tools/quick-bar/#my-links). Selecting a My link opens that page in their own Home Assistant installation.
-Screenshot showing the styling of my links:
+For example: `"Go to {% my integrations title="**Settings** > **Devices & services**" %} and select your integration."`
+
+ Screenshot showing the styling of my links
+
-Here are a few examples:
+#### Examples
```markdown
- {% my areas title="**Settings** > **Areas, labels & zones**" %}
@@ -48,14 +51,15 @@ To identify a My link, in Home Assistant, open the page of interest and press th
Some Home Assistant terms and concepts are explained in a Glossary. If you add a reference to the definition of such a term, the term definition is shown as a tooltip.
-Screenshot showing the styling of a glossary term tooltip:
-
+
+ Screenshot showing the styling of a glossary term tooltip
+
-For example:
+#### Examples
```markdown
{% term integration %}
@@ -72,14 +76,15 @@ If possible, try to avoid using abbreviations and acronyms.
If you want to use an acronym or abbreviation, you can add an abbreviation tag to show the full term as a tooltip.
-Screenshot showing the styling of an abbreviation tooltip:
-
+
+ Screenshot showing the styling of an abbreviation tooltip
+
-Here a few examples:
+#### Examples
```markdown
A/V,
@@ -99,14 +104,15 @@ or USB-OTG.
To refer to an icon in the UI, you can use icons from the [Iconify library](https://icon-sets.iconify.design/mdi/).
-Screenshot showing some inline icons:
-
+
+ Screenshot showing some inline icons
+
-Here are some examples:
+#### Examples
```markdown
- Three dots menu: {% icon "mdi:dots-vertical" %}
@@ -131,14 +137,15 @@ Here are some examples:
Use a details block to make a text block collapsible:
-Screenshot showing a collapsible text block:
-
+
+ Screenshot showing a collapsible text block
+
-Example:
+### Example
```markdown
{% details "Generate Client ID and Client Secret" %}
@@ -152,16 +159,22 @@ Example:
## Text boxes
-Screenshot showing text boxes:
+
+ 
+ Screenshot showing text boxes:
+
-
-
-Example:
+### Examples
```markdown
+
+{% tip %}
+You can use a tip to feature a recommendation.
+{% endtip %}
+
{% note %}
You can use a note to highlight a section.
{% endnote %}
@@ -177,12 +190,13 @@ For some topics, there are predefined text elements that you can reuse.
### Configuration
-Screenshot showing the predefined configuration text block:
-
+
+ Screenshot showing the predefined configuration text block
+
To use this element, add the following line:
@@ -190,9 +204,55 @@ To use this element, add the following line:
{% include integrations/config_flow.md %}
```
+#### Configuration_basic block
+
+Use the `configuration_basic` block to describe configuration options if your integration is set up via a config flow.
+
+
+ 
+ Screenshot showing a configuration variable block for integrations that are set up in the UI
+
+
+```markdown
+{% configuration_basic %}
+Host:
+ description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**."
+Local access token:
+ description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**."
+{% endconfiguration_basic %}
+```
+
+#### Configuration block for YAML integrations
+
+Use the `configuration` block to describe configuration options if your integration is set up via YAML only.
+
+
+ 
+ Screenshot showing a configuration variable block for YAML integrations
+
+
+```markdown
+{% configuration %}
+Host:
+ description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**."
+ required: false
+ type: string
+Local access token:
+ description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**."
+ required: false
+ type: string
+{% endconfiguration %}
+```
+
## Images
-You can use an image to illustrate a step:
+In general, use the Markdown syntax to add images. For example, when adding an image to illustrate a step:
```
+
+ Screencast showing a reference to Youtube to start at a specific time
+
-## Document structure with example text
+## Document structure
-This section outlines the document structure. To view example text, refer to the integration documentation template in the `homeassistant.io` repository under `/_integrations/_integration_docs_template.md`. The example text includes some reusable text blocks (includes) such as `include integrations/config_flow.md` and styling elements such as `configuration_basic`.
+This section outlines the high-level document structure. To view example text, refer to the integration documentation template in the `homeassistant.io` repository under `/_integrations/_integration_docs_template.md`. The example text includes some reusable text blocks (includes) such as `include integrations/config_flow.md` and styling elements such as `configuration_basic`.
The examples are taken from the [Integration Quality Scale](/docs/core/integration-quality-scale/).