diff --git a/docs/documenting/integration-docs-examples.md b/docs/documenting/integration-docs-examples.md new file mode 100644 index 00000000..bf1e0efd --- /dev/null +++ b/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: + +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: + +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: + +Screenshot showing the styling of an abbreviation tooltip + +Here a few examples: + +```markdown +A/V, +CT, +DSMR, +eMMC, +FLV, +LLMs, +MCP, +PTZ, +RTMP, +RTSP, +or USB-OTG. +``` + +### 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: + +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: + +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: + +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: + +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: + +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: + +Screenshot showing an image with an image caption + +HTML syntax to add an image, example: + +```html +

Screenshot of tile cards with features. +Screenshot of tile cards with features. +

+``` + +## 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 + +``` + +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 diff --git a/sidebars.js b/sidebars.js index a91bc636..2871d958 100644 --- a/sidebars.js +++ b/sidebars.js @@ -296,6 +296,7 @@ module.exports = { "documenting/standards", "documenting/yaml-style-guide", "documenting/create-page", + "documenting/integration-docs-examples", ], }, diff --git a/static/img/en/documentation/abbreviation_tooltip.png b/static/img/en/documentation/abbreviation_tooltip.png new file mode 100644 index 00000000..8560558d Binary files /dev/null and b/static/img/en/documentation/abbreviation_tooltip.png differ diff --git a/static/img/en/documentation/collapsible_text_block.png b/static/img/en/documentation/collapsible_text_block.png new file mode 100644 index 00000000..75525a1c Binary files /dev/null and b/static/img/en/documentation/collapsible_text_block.png differ diff --git a/static/img/en/documentation/collapsible_text_block.webp b/static/img/en/documentation/collapsible_text_block.webp new file mode 100644 index 00000000..04deb8a0 Binary files /dev/null and b/static/img/en/documentation/collapsible_text_block.webp differ diff --git a/static/img/en/documentation/config_flow.png b/static/img/en/documentation/config_flow.png new file mode 100644 index 00000000..a611d24a Binary files /dev/null and b/static/img/en/documentation/config_flow.png differ diff --git a/static/img/en/documentation/configuration_variables_ui.png b/static/img/en/documentation/configuration_variables_ui.png new file mode 100644 index 00000000..81d023ad Binary files /dev/null and b/static/img/en/documentation/configuration_variables_ui.png differ diff --git a/static/img/en/documentation/configuration_variables_yaml.png b/static/img/en/documentation/configuration_variables_yaml.png new file mode 100644 index 00000000..01d3df78 Binary files /dev/null and b/static/img/en/documentation/configuration_variables_yaml.png differ diff --git a/static/img/en/documentation/glossary-term_tooltip.png b/static/img/en/documentation/glossary-term_tooltip.png new file mode 100644 index 00000000..402a180f Binary files /dev/null and b/static/img/en/documentation/glossary-term_tooltip.png differ diff --git a/static/img/en/documentation/image_in_step.png b/static/img/en/documentation/image_in_step.png new file mode 100644 index 00000000..971a06c8 Binary files /dev/null and b/static/img/en/documentation/image_in_step.png differ diff --git a/static/img/en/documentation/image_with_legend.png b/static/img/en/documentation/image_with_legend.png new file mode 100644 index 00000000..bccc97a2 Binary files /dev/null and b/static/img/en/documentation/image_with_legend.png differ diff --git a/static/img/en/documentation/inline_icons.png b/static/img/en/documentation/inline_icons.png new file mode 100644 index 00000000..5f522d99 Binary files /dev/null and b/static/img/en/documentation/inline_icons.png differ diff --git a/static/img/en/documentation/my-links_formatting.png b/static/img/en/documentation/my-links_formatting.png new file mode 100644 index 00000000..a7aff0d2 Binary files /dev/null and b/static/img/en/documentation/my-links_formatting.png differ diff --git a/static/img/en/documentation/text_boxes.png b/static/img/en/documentation/text_boxes.png new file mode 100644 index 00000000..3b6bf66a Binary files /dev/null and b/static/img/en/documentation/text_boxes.png differ diff --git a/static/img/en/documentation/youtube_ref_start_at.webp b/static/img/en/documentation/youtube_ref_start_at.webp new file mode 100644 index 00000000..0eb7b7d4 Binary files /dev/null and b/static/img/en/documentation/youtube_ref_start_at.webp differ