jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-19 15:26:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documenting: apply sentence-style capitalization to headings (#2184)

Browse Source 
- to comply with MS Style Guide on [capitalization](https://learn.microsoft.com/en-us/style-guide/capitalization)
This commit is contained in:
c0ffeeca7 2024-05-23 09:59:57 +02:00 committed by GitHub
parent 2a1a921bcd
commit ce87985970
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 11 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/documenting/create-page.md
View File

@ -29,7 +29,7 @@ related:
Content... Written in markdown. Content... Written in markdown.
### Title Header ### Title header
... ...
``` ```
@ -97,7 +97,7 @@ required: any string here #=> Any string here
- **`type:`**: The type of the variable. Allowed entries: `action`, `boolean`, `string`, `integer`, `float`, `time`, `template`, `device_class`, `icon`, `map`/`list` (for a list of entries), `date`, `datetime`, `selector`, and `any`. For multiple possibilities use `[string, integer]`. If you use `map`/`list` then should define `keys:` (see the [`template` sensor](https://www.home-assistant.io/integrations/sensor.template/) for an example). If you use `boolean`, then `default:` must be defined. - **`type:`**: The type of the variable. Allowed entries: `action`, `boolean`, `string`, `integer`, `float`, `time`, `template`, `device_class`, `icon`, `map`/`list` (for a list of entries), `date`, `datetime`, `selector`, and `any`. For multiple possibilities use `[string, integer]`. If you use `map`/`list` then should define `keys:` (see the [`template` sensor](https://www.home-assistant.io/integrations/sensor.template/) for an example). If you use `boolean`, then `default:` must be defined.
### Embedding Code ### Embedding code
You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in back-ticks. You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in back-ticks.
@ -144,6 +144,6 @@ Other images, displayed on the pages, are stored in various directories accordin
| blog | source/images/blog | | blog | source/images/blog |
| screenshots | source/images/integration | | screenshots | source/images/integration |
### Linking From The Sidebar ### Linking from the sidebar
If you are adding a new page that requires linking from the sidebar, you need to edit the `docs_navigation.html` file in `source/_includes/asides/docs_navigation.html`. If you are adding a new page that requires linking from the sidebar, you need to edit the `docs_navigation.html` file in `source/_includes/asides/docs_navigation.html`.

16
docs/documenting/standards.md
View File

@ -4,7 +4,7 @@ title: "Standards"
To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation. To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation.
## General Documentation ## General documentation
Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://learn.microsoft.com/style-guide/welcome/). Broadly speaking documentation should be written following Microsoft's house style, which is detailed [here](https://learn.microsoft.com/style-guide/welcome/).
@ -17,13 +17,13 @@ Broadly speaking documentation should be written following Microsoft's house sty
- Do not use ALL CAPITALS for emphasis - use _italics_ instead. - Do not use ALL CAPITALS for emphasis - use _italics_ instead.
- All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` tag. - All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` tag.
## Integration and Platform Pages ## Integration and platform pages
- All examples should be formatted to be included in `configuration.yaml` unless explicitly stated. - All examples should be formatted to be included in `configuration.yaml` unless explicitly stated.
- Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`. - Use capital letters and `_` to indicate that the value needs to be replaced. E.g., `api_key: YOUR_API_KEY` or `api_key: REPLACE_ME`.
- Integration and platform names should be a link to their respective documentation pages. - Integration and platform names should be a link to their respective documentation pages.
### Configuration Variables ### Configuration variables
- The **Configuration Variables** section is only used for YAML configuration. - The **Configuration Variables** section is only used for YAML configuration.
- The **Configuration Variables** section must use the `{% configuration %}` tag. - The **Configuration Variables** section must use the `{% configuration %}` tag.
@ -32,7 +32,7 @@ Broadly speaking documentation should be written following Microsoft's house sty
- Configuration variables must document the accepted value types (see [Configuration variables details](documenting/create-page.md#configuration)). - Configuration variables must document the accepted value types (see [Configuration variables details](documenting/create-page.md#configuration)).
- For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, integer`). - For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, integer`).
#### Example Configuration Variables Block #### Example configuration variables block
```yaml ```yaml
{% configuration %} {% configuration %}
@ -44,7 +44,7 @@ some_key:
{% endconfiguration %} {% endconfiguration %}
``` ```
### UI Variables ### UI variables
- For describing **UI Variables** the `{% configuration_basic %}` section can be used. - For describing **UI Variables** the `{% configuration_basic %}` section can be used.
@ -55,14 +55,14 @@ some_key:
- Less content makes tables easier to read - Less content makes tables easier to read
- When limiting the amount of text is not possible, consider using other data structures for representing the information. For example, lists or `{% configuration_basic %}` can be used. - When limiting the amount of text is not possible, consider using other data structures for representing the information. For example, lists or `{% configuration_basic %}` can be used.
## YAML and Templates ## YAML and templates
We have a separate styling guide for YAML and the use of Jinja2 templates We have a separate styling guide for YAML and the use of Jinja2 templates
inside that YAML. inside that YAML.
[YAML Style Guide](documenting/yaml-style-guide.md) [YAML Style Guide](documenting/yaml-style-guide.md)
## Glossary & Terminology Tooltips ## Glossary & terminology tooltips
The documentation should be written in a way that is understandable for The documentation should be written in a way that is understandable for
everyone. To help with that, we have a [glossary of terms](https://www.home-assistant.io/docs/glossary/) everyone. To help with that, we have a [glossary of terms](https://www.home-assistant.io/docs/glossary/)
@ -103,7 +103,7 @@ Awesome, because this allowed me to {% term automation "automate everything" %}
in my home! I love it! in my home! I love it!
``` ```
## Renaming Pages ## Renaming pages
It can happen that an integration or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add an entry to the `_redirects` file as shown below. Please consider to add details, like release number or old integration/platform name, to the page in a [note](/documenting/create-page.md/#html). It can happen that an integration or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add an entry to the `_redirects` file as shown below. Please consider to add details, like release number or old integration/platform name, to the page in a [note](/documenting/create-page.md/#html).