Skip to content

Commit 8589e39

Browse files
c0ffeeca7c0ffeeca7
authored
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
1 parent dc8a702 commit 8589e39

15 files changed

+260
-0
lines changed

‎docs/documenting/integration-docs-examples.md

+259
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
---
2+
title: Documentation structure and example text
3+
---
4+
5+
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.
6+
7+
Use this template together with the following documentation:
8+
9+
- 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).
10+
- [Documentation standard](https://developers.home-assistant.io/docs/documenting/standards).
11+
- The documentation rules of the [Integration Quality Scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/).
12+
13+
## Inline text elements
14+
15+
This section shows elements you can use within your text.
16+
17+
### My links
18+
19+
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."`
20+
21+
Screenshot showing the styling of my links:
22+
23+
<img class='invertDark'
24+
src='/img/en/documentation/my-links_formatting.png'
25+
alt='Screenshot showing the styling of my links'
26+
/>
27+
28+
Here are a few examples:
29+
30+
```markdown
31+
- {% my areas title="**Settings** > **Areas, labels & zones**" %}
32+
- {% my automations title="**Settings** > **Automations & scenes**" %}
33+
- {% my backup title="**Settings** > **System** > **Backups**" %}
34+
- {% my general title="**Settings** > **System** > **General**" %}
35+
- {% my logs title="**Settings** > **System** > **Logs**" %}
36+
- {% my network title="**Settings** > **System** > **Network**" %}
37+
- {% my profile title="**User profile**" %}
38+
```
39+
40+
To identify a My link, in Home Assistant, open the page of interest and press the `m` key.
41+
42+
### Formatting
43+
44+
- Use bold when referring to UI strings: **Settings**, **Areas, labels & zones**
45+
- 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`.
46+
47+
### Glossary term reference
48+
49+
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.
50+
51+
Screenshot showing the styling of a glossary term tooltip:
52+
53+
<img class='invertDark'
54+
src='/img/en/documentation/glossary-term_tooltip.png'
55+
alt='Screenshot showing the styling of a glossary term tooltip'
56+
/>
57+
58+
For example:
59+
60+
```markdown
61+
{% term integration %}
62+
{% term entity %}
63+
{% term "configuration.yaml" %}
64+
{% term "Home Assistant Operating System" %}
65+
```
66+
67+
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).
68+
69+
### Acronyms and abbreviations
70+
71+
If possible, try to avoid using abbreviations and acronyms.
72+
73+
If you want to use an acronym or abbreviation, you can add an abbreviation tag to show the full term as a tooltip.
74+
75+
Screenshot showing the styling of an abbreviation tooltip:
76+
77+
<img class='invertDark'
78+
src='/img/en/documentation/abbreviation_tooltip.png'
79+
alt='Screenshot showing the styling of an abbreviation tooltip'
80+
/>
81+
82+
Here a few examples:
83+
84+
```markdown
85+
<abbr title="Audio & video">A/V</abbr>,
86+
<abbr title="current transformers">CT</abbr>,
87+
<abbr title="Dutch smart meter requirement">DSMR</abbr>,
88+
<abbr title="embedded MultiMediaCard">eMMC</abbr>,
89+
<abbr title="flash video">FLV</abbr>,
90+
<abbr title="Large Language Models">LLMs</abbr>,
91+
<abbr title="Model Context Protocol">MCP</abbr>,
92+
<abbr title="pan, tilt, and zoom">PTZ</abbr>,
93+
<abbr title="real-time messaging protocol">RTMP</abbr>,
94+
<abbr title="real-time streaming protocol">RTSP</abbr>,
95+
or <abbr title="USB-On-The-Go">USB-OTG</abbr>.
96+
```
97+
98+
### Inline icons
99+
100+
To refer to an icon in the UI, you can use icons from the [Iconify library](https://icon-sets.iconify.design/mdi/).
101+
102+
Screenshot showing some inline icons:
103+
104+
<img class='invertDark'
105+
src='/img/en/documentation/inline_icons.png'
106+
alt='Screenshot showing some inline icons'
107+
/>
108+
109+
Here are some examples:
110+
111+
```markdown
112+
- Three dots menu: {% icon "mdi:dots-vertical" %}
113+
- Hamburger menu: {% icon "mdi:menu" %}
114+
- Edit: {% icon "mdi:edit" %}
115+
- Revert {% icon "mdi:restore" %}
116+
- Eye: {% icon "mdi:eye" %}
117+
- Trash: {% icon "mdi:trash" %}
118+
- Cog: {% icon "mdi:cog" %}
119+
- Cog outline: {% icon "mdi:cog-outline" %}
120+
- Drag: {% icon "mdi:drag" %}
121+
- Move-cursor: {% icon "mdi:cursor-move" %}
122+
- Arrow left: {% icon "mdi:arrow-left-bold" %}
123+
- Arrow right: {% icon "mdi:arrow-right-bold" %}
124+
- Checkbox list: {% icon "mdi:order-checkbox-ascending" %}
125+
- Upload network: {% icon "mdi:upload-network" %}
126+
- Security network: {% icon "mdi:security-network" %}
127+
- Routes: {% icon "mdi:routes" %}
128+
```
129+
130+
## Collapsible text block
131+
132+
Use a details block to make a text block collapsible:
133+
134+
Screenshot showing a collapsible text block:
135+
136+
<img class='invertDark'
137+
src='/img/en/documentation/collapsible_text_block.webp'
138+
alt='Screenshot showing a collapsible text block'
139+
/>
140+
141+
Example:
142+
143+
```markdown
144+
{% details "Generate Client ID and Client Secret" %}
145+
146+
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.
147+
2. Visit the [fitbit developer page](https://dev.fitbit.com/apps/new) to register an application.
148+
3. Enter an **Application Name** of your choosing, for example **Home Assistant**.
149+
4. ...
150+
{% enddetails %}
151+
```
152+
153+
## Text boxes
154+
155+
Screenshot showing text boxes:
156+
157+
<img class='invertDark'
158+
src='/img/en/documentation/text_boxes.png'
159+
alt='Screenshot showing text boxes'
160+
/>
161+
162+
Example:
163+
164+
```markdown
165+
{% note %}
166+
You can use a note to highlight a section.
167+
{% endnote %}
168+
169+
{% important %}
170+
You can use "important" to highlight a section that you feel is very important.
171+
{% endimportant %}
172+
```
173+
174+
## Reusable text
175+
176+
For some topics, there are predefined text elements that you can reuse.
177+
178+
### Configuration
179+
180+
Screenshot showing the predefined configuration text block:
181+
182+
<img class='invertDark'
183+
src='/img/en/documentation/config_flow.png'
184+
alt='Screenshot showing predefined configuration text block'
185+
/>
186+
187+
To use this element, add the following line:
188+
189+
```markdown
190+
{% include integrations/config_flow.md %}
191+
```
192+
193+
## Images
194+
195+
You can use an image to illustrate a step:
196+
197+
<img class='invertDark'
198+
src='/img/en/documentation/image_in_step.png'
199+
alt='Screenshot showing an image to illustrate a step'
200+
/>
201+
202+
Markdown syntax to add an image:
203+
204+
```markdown
205+
1. To adjust the light temperature and brightness, move the sliders:
206+
![Screenshot of tile cards with features](/images/dashboards/features/screenshot-tile-feature-grid.png)
207+
2. Then do this ...
208+
```
209+
210+
You can add an image with caption:
211+
212+
<img class='invertDark'
213+
src='/img/en/documentation/image_with_legend.png'
214+
alt='Screenshot showing an image with an image caption'
215+
/>
216+
217+
HTML syntax to add an image, example:
218+
219+
```html
220+
<p class='img'><img src='/images/dashboards/features/screenshot-tile-feature-grid.png' alt="Screenshot of tile cards with features.">
221+
Screenshot of tile cards with features.
222+
</p>
223+
```
224+
225+
## Videos
226+
227+
Use the following syntax to reference a video from Youtube. Use `videoStartAt` to have it start playback at a specific time in the video:
228+
229+
```html
230+
<lite-youtube videoid="ZgoaoTpIhm8" videoStartAt="3907" videotitle="Introducing the Home Assistant Voice Preview Edition - Voice: Chapter 8"></lite-youtube>
231+
```
232+
233+
<img class='invertDark'
234+
src='/img/en/documentation/youtube_ref_start_at.webp'
235+
alt='Screencast showing a refernce to Youtube to start at a specific time'
236+
/>
237+
238+
## Document structure with example text
239+
240+
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`.
241+
242+
The examples are taken from the [Integration Quality Scale](/docs/core/integration-quality-scale/).
243+
244+
### Basic structure
245+
246+
- Introduction
247+
- Use case
248+
- Supported/unsupported devices
249+
- Prerequisites
250+
- Configuration
251+
- Configuration options
252+
- Supported functionality
253+
- Actions
254+
- Examples
255+
- Data updates
256+
- Known limitations
257+
- Troubleshooting
258+
- Community notes
259+
- Removing the integration

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,7 @@ module.exports = {
296296
"documenting/standards",
297297
"documenting/yaml-style-guide",
298298
"documenting/create-page",
299+
"documenting/integration-docs-examples",
299300
],
300301
},
301302

‎static/img/en/documentation/abbreviation_tooltip.png

25 KB
Loading

‎static/img/en/documentation/collapsible_text_block.png

8.76 KB
Loading

‎static/img/en/documentation/collapsible_text_block.webp

60.2 KB
Binary file not shown.

‎static/img/en/documentation/config_flow.png

70.8 KB
Loading

‎static/img/en/documentation/configuration_variables_ui.png

25.7 KB
Loading

‎static/img/en/documentation/configuration_variables_yaml.png

46.6 KB
Loading

‎static/img/en/documentation/glossary-term_tooltip.png

46.7 KB
Loading

‎static/img/en/documentation/image_in_step.png

37.4 KB
Loading

‎static/img/en/documentation/image_with_legend.png

29.4 KB
Loading

‎static/img/en/documentation/inline_icons.png

33.2 KB
Loading

‎static/img/en/documentation/my-links_formatting.png

21.9 KB
Loading

‎static/img/en/documentation/text_boxes.png

22.5 KB
Loading

‎static/img/en/documentation/youtube_ref_start_at.webp

544 KB
Binary file not shown.

0 commit comments

Comments
 (0)