Add documentation about creating integration documentation (#2541)

* Add documentation about creating integration documentation

- showcases some documentation features such as glossary entries, My links, collapsible text, and reuse elements
- shows the documentation structure
- shows the example text from the integration quality scale

* Add section on reuse

* code fence to fix build error

* Remove links that no longer work after code fencing the rest of the text

* Rephrase

* Code fence elements to fix build

* Fix link

* Video: improve intro para

* Fix links

* Fix more links..

* Improve structure

- example text: add titles
- configuration section: add screenshots

* Structure list: add link to example text sections

* Attempt to fix build

* Attempt to fix build

* Fix list

* Fix header

* Revert heading level change

* remove example text and refer to template instead

* Update intro

* Update docs/documenting/lorem-ipsum.md

* Rename file name from lorem-ipsum to integration-docs-examples

docs/documenting/integration-docs-examples.md

@@ -0,0 +1,259 @@
+---
+title: Documentation structure and example text
+---
+
+This page shows examples of the available documentation features (such as inline icons, text box, links to related topics, and glossary entries). It also shows the documentation structure.
+
+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).
+- [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/).
+
+## Inline text elements
+
+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."`
+
+Screenshot showing the styling of my links:
+
+<img class='invertDark'
+    src='/img/en/documentation/my-links_formatting.png'
+    alt='Screenshot showing the styling of my links'
+  />
+
+Here are a few examples:
+
+```markdown
+- {% my areas title="**Settings** > **Areas, labels & zones**" %}
+- {% my automations title="**Settings** > **Automations & scenes**" %}
+- {% my backup title="**Settings** > **System** > **Backups**" %}
+- {% my general title="**Settings** > **System** > **General**" %}
+- {% my logs title="**Settings** > **System** > **Logs**" %}
+- {% my network title="**Settings** > **System** > **Network**" %}
+- {% my profile title="**User profile**" %}
+```
+
+To identify a My link, in Home Assistant, open the page of interest and press the `m` key.
+
+### Formatting
+
+- Use bold when referring to UI strings: **Settings**, **Areas, labels & zones**
+- Use backtick when referring to file paths, file names, variable names, or a text that you enter in a field: the `/boot/config.txt` file, the `this` variable, enter `/newbot`.
+
+### Glossary term reference
+
+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:
+
+<img class='invertDark'
+    src='/img/en/documentation/glossary-term_tooltip.png'
+    alt='Screenshot showing the styling of a glossary term tooltip'
+  />
+
+For example:
+
+```markdown
+{% term integration %}
+{% term entity %}
+{% term "configuration.yaml" %}
+{% term "Home Assistant Operating System" %}
+```
+
+You can find the full list of glossary terms on the [Glossary](https://www.home-assistant.io/docs/glossary/) page. To learn more about glossary terms, refer to the [developer documentation on glossary](/docs/documenting/standards#glossary--terminology-tooltips).
+
+### Acronyms and abbreviations
+
+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:
+
+<img class='invertDark'
+    src='/img/en/documentation/abbreviation_tooltip.png'
+    alt='Screenshot showing the styling of an abbreviation tooltip'
+  />
+
+Here a few examples:
+
+```markdown
+<abbr title="Audio & video">A/V</abbr>,
+<abbr title="current transformers">CT</abbr>,
+<abbr title="Dutch smart meter requirement">DSMR</abbr>,
+<abbr title="embedded MultiMediaCard">eMMC</abbr>,
+<abbr title="flash video">FLV</abbr>,
+<abbr title="Large Language Models">LLMs</abbr>,
+<abbr title="Model Context Protocol">MCP</abbr>,
+<abbr title="pan, tilt, and zoom">PTZ</abbr>,
+<abbr title="real-time messaging protocol">RTMP</abbr>,
+<abbr title="real-time streaming protocol">RTSP</abbr>,
+or <abbr title="USB-On-The-Go">USB-OTG</abbr>.
+```
+
+### Inline icons
+
+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:
+
+<img class='invertDark'
+    src='/img/en/documentation/inline_icons.png'
+    alt='Screenshot showing some inline icons'
+  />
+
+Here are some examples:
+
+```markdown
+- Three dots menu: {% icon "mdi:dots-vertical" %}
+- Hamburger menu: {% icon "mdi:menu" %}
+- Edit: {% icon "mdi:edit" %}
+- Revert {% icon "mdi:restore" %}
+- Eye: {% icon "mdi:eye" %}
+- Trash: {% icon "mdi:trash" %}
+- Cog: {% icon "mdi:cog" %}
+- Cog outline: {% icon "mdi:cog-outline" %}
+- Drag: {% icon "mdi:drag" %}
+- Move-cursor: {% icon "mdi:cursor-move" %}
+- Arrow left: {% icon "mdi:arrow-left-bold" %}
+- Arrow right: {% icon "mdi:arrow-right-bold" %}
+- Checkbox list: {% icon "mdi:order-checkbox-ascending" %}
+- Upload network: {% icon "mdi:upload-network" %}
+- Security network: {% icon "mdi:security-network" %}
+- Routes: {% icon "mdi:routes" %}
+```
+
+## Collapsible text block
+
+Use a details block to make a text block collapsible:
+
+Screenshot showing a collapsible text block:
+
+<img class='invertDark'
+    src='/img/en/documentation/collapsible_text_block.webp'
+    alt='Screenshot showing a collapsible text block'
+  />
+
+Example:
+
+```markdown
+{% details "Generate Client ID and Client Secret" %}
+
+1. Your Fitbit account must be registered as a Developer account at the [Fitbit Developer Portal](https://dev.fitbit.com), and have a verified email address.
+2. Visit the [fitbit developer page](https://dev.fitbit.com/apps/new) to register an application.
+3. Enter an **Application Name** of your choosing, for example **Home Assistant**.
+4. ...
+{% enddetails %}
+```
+
+## Text boxes
+
+Screenshot showing text boxes:
+
+<img class='invertDark'
+    src='/img/en/documentation/text_boxes.png'
+    alt='Screenshot showing text boxes'
+  />
+
+Example:
+
+```markdown
+{% note %}
+You can use a note to highlight a section.
+{% endnote %}
+
+{% important %}
+You can use "important" to highlight a section that you feel is very important.
+{% endimportant %}
+```
+
+## Reusable text
+
+For some topics, there are predefined text elements that you can reuse.
+
+### Configuration
+
+Screenshot showing the predefined configuration text block:
+
+<img class='invertDark'
+    src='/img/en/documentation/config_flow.png'
+    alt='Screenshot showing predefined configuration text block'
+  />
+
+To use this element, add the following line:
+
+```markdown
+{% include integrations/config_flow.md %}
+```
+
+## Images
+
+You can use an image to illustrate a step:
+
+<img class='invertDark'
+    src='/img/en/documentation/image_in_step.png'
+    alt='Screenshot showing an image to illustrate a step'
+  />
+
+Markdown syntax to add an image:
+
+```markdown
+1. To adjust the light temperature and brightness, move the sliders:
+    ![Screenshot of tile cards with features](/images/dashboards/features/screenshot-tile-feature-grid.png)
+2. Then do this ...
+```
+
+You can add an image with caption:
+
+<img class='invertDark'
+    src='/img/en/documentation/image_with_legend.png'
+    alt='Screenshot showing an image with an image caption'
+  />
+
+HTML syntax to add an image, example:
+
+```html
+<p class='img'><img src='/images/dashboards/features/screenshot-tile-feature-grid.png' alt="Screenshot of tile cards with features.">
+Screenshot of tile cards with features.
+</p>
+```
+
+## Videos
+
+Use the following syntax to reference a video from Youtube. Use `videoStartAt` to have it start playback at a specific time in the video:
+
+```html
+<lite-youtube videoid="ZgoaoTpIhm8" videoStartAt="3907" videotitle="Introducing the Home Assistant Voice Preview Edition - Voice: Chapter 8"></lite-youtube>
+```
+
+<img class='invertDark'
+    src='/img/en/documentation/youtube_ref_start_at.webp'
+    alt='Screencast showing a refernce to Youtube to start at a specific time'
+  />
+
+## Document structure with example text
+
+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`.
+
+The examples are taken from the [Integration Quality Scale](/docs/core/integration-quality-scale/).
+
+### Basic structure
+
+- Introduction
+  - Use case
+- Supported/unsupported devices
+- Prerequisites
+- Configuration
+- Configuration options
+- Supported functionality
+- Actions
+- Examples
+- Data updates
+- Known limitations
+- Troubleshooting
+- Community notes
+- Removing the integration

sidebars.js

@@ -296,6 +296,7 @@ module.exports = {
         "documenting/standards",
         "documenting/yaml-style-guide",
         "documenting/create-page",
+        "documenting/integration-docs-examples",
       ],
     },