From 8589e39d33ebbd4555c8acc1da5b0d5f0d88766b Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Thu, 20 Feb 2025 22:11:34 +0100
Subject: [PATCH] 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 | 259 ++++++++++++++++++
sidebars.js | 1 +
.../en/documentation/abbreviation_tooltip.png | Bin 0 -> 25631 bytes
.../documentation/collapsible_text_block.png | Bin 0 -> 8971 bytes
.../documentation/collapsible_text_block.webp | Bin 0 -> 61676 bytes
static/img/en/documentation/config_flow.png | Bin 0 -> 72542 bytes
.../configuration_variables_ui.png | Bin 0 -> 26342 bytes
.../configuration_variables_yaml.png | Bin 0 -> 47731 bytes
.../documentation/glossary-term_tooltip.png | Bin 0 -> 47812 bytes
static/img/en/documentation/image_in_step.png | Bin 0 -> 38295 bytes
.../en/documentation/image_with_legend.png | Bin 0 -> 30091 bytes
static/img/en/documentation/inline_icons.png | Bin 0 -> 33947 bytes
.../en/documentation/my-links_formatting.png | Bin 0 -> 22404 bytes
static/img/en/documentation/text_boxes.png | Bin 0 -> 23046 bytes
.../documentation/youtube_ref_start_at.webp | Bin 0 -> 557396 bytes
15 files changed, 260 insertions(+)
create mode 100644 docs/documenting/integration-docs-examples.md
create mode 100644 static/img/en/documentation/abbreviation_tooltip.png
create mode 100644 static/img/en/documentation/collapsible_text_block.png
create mode 100644 static/img/en/documentation/collapsible_text_block.webp
create mode 100644 static/img/en/documentation/config_flow.png
create mode 100644 static/img/en/documentation/configuration_variables_ui.png
create mode 100644 static/img/en/documentation/configuration_variables_yaml.png
create mode 100644 static/img/en/documentation/glossary-term_tooltip.png
create mode 100644 static/img/en/documentation/image_in_step.png
create mode 100644 static/img/en/documentation/image_with_legend.png
create mode 100644 static/img/en/documentation/inline_icons.png
create mode 100644 static/img/en/documentation/my-links_formatting.png
create mode 100644 static/img/en/documentation/text_boxes.png
create mode 100644 static/img/en/documentation/youtube_ref_start_at.webp
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:
+
+
+
+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:
+
+
+
+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:
+
+
+
+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:
+
+
+
+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:
+
+
+
+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:
+
+
+
+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:
+
+
+
+To use this element, add the following line:
+
+```markdown
+{% include integrations/config_flow.md %}
+```
+
+## Images
+
+You can use an image to illustrate a step:
+
+
+
+Markdown syntax to add an image:
+
+```markdown
+1. To adjust the light temperature and brightness, move the sliders:
+ 
+2. Then do this ...
+```
+
+You can add an image with caption:
+
+
+
+HTML syntax to add an image, example:
+
+```html
+
+Screenshot of tile cards with features.
+
-=@lR-T1NFWw?4CM{o-!gL^+0N@$HW
z?1>)jXAE>m5|H}juplXn)7iS)bbZNTl}vK{uFP6dSwJD;&R13KAAO5sCTnChV$NIN
z@%2lyen-fcd%L`Q2_Gh{e 9z
z<(SZxCV`yTzP75AfKoibWm3EhQK1UA4E=Vkyxn$DkJFkFPnm!E-?R9Dj*i-NmrQKd
zeTD2Gj)6>_Bt(Xc93wxrFOQDcTaUs6m(>^$4j)rW27ZV8n0Zx*>%t1&E1DM(?aAFx
zt{WTaTOy<{xvdqplQ3BJ>BqlU0TA_5V_@Fr!qK$CyfpC@=v^ZHMvc>{q~b !1;F`+3pXkjZ-Jmdx{tT>rPw!0rO1AtpRN%BAN+TQ@^V}kk+ofYZ?I#z{ue7?U
zIoP!ci*I$yfm+qXv3I?{0G;@c@>}k0t#8va(MoAbQf-iN&NPvWz#sxa&qZ0&k|<()
z-D?KKp2FF-ssR`8o(lww
zGP$ar*w{k4?V3PR
zxJW_z(CrnbbDE;4CC$y34u|$T*QN~*n;$xKsLW;L5U_{lp%)^Dfu(OetDkU#ui%Ga
z6PWMwoI2G61_y3n5Rjn-963%i;vwTI#XU(@#gr<4>z{`zr`+wuh7jA-Jhxt8(dd6q
zVA@``O}q!|k}B&R1^B6UAjcV^_}TC451UDCV`Gi3k9UhNB9VWhVFXd!(hZ>cI2HWM
zh*OEFn%N}6gGZK@b{J_i5F{%H#~oNDn444vYTGvJ%Xw+(q=Ws9TGTcB;s<&0>A4kg
z#3^osW`;uE9B?6zn@k$F{L{F-osE=$yd#GXcNAKwFI15=d3ky5@I37qidz2u{`0}X
zxRGJl;FFPz!2gQChgp8dLBG`1)p1edK%?7&_bSHea&pT7IcVnU=Y50mI=OgNrX6P&
z+4R)QX&y$fpY0YA63Tr4z9F{~tn8-)FdSi#krxF7ek{7~QkHt9>;13)VP^iHs|igm
z3
yTc+>7Wx;R-%CQkkleHI
zM@CxD9}|uU2r0KydSCwnW)$swmNY!=?R}?TT?QU1HunZ_V#?;Q?nKIvOCA-cFcPyO
zRJpfTYH)oY;Q={Zmt3%6oY#M!0&unOzM_QinON<_(e8IlLI|4qS*4zReM%QRC3S{D
zWXyzA{1#s$;z;DEvlo)|yyHC2U87A;es1J2c!j1zY@z%ANjsp?#j=XfTa^4pK=>6k
zk}3)#+!88DVc%|weiVxF@>R1$cpX;0$d4)hs