From 95cf82f53b776f51da03b1e3aae13ed853d16474 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Mon, 2 Jul 2018 23:02:49 +0200 Subject: [PATCH] Move documentation docs (fixes #19) (#47) --- docs/documentation_create_page.md | 120 ++++++++++++++++++++++++++++++ docs/documentation_index.md | 36 +++++++++ docs/documentation_standards.md | 110 +++++++++++++++++++++++++++ website/sidebars.json | 5 ++ 4 files changed, 271 insertions(+) create mode 100644 docs/documentation_create_page.md create mode 100644 docs/documentation_index.md create mode 100644 docs/documentation_standards.md diff --git a/docs/documentation_create_page.md b/docs/documentation_create_page.md new file mode 100644 index 00000000..59d6d755 --- /dev/null +++ b/docs/documentation_create_page.md @@ -0,0 +1,120 @@ +--- +title: "Create a new page" +--- + +For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](https://www.home-assistant.io/components/) and the [Examples section](https://www.home-assistant.io/cookbook/) are generated automatically, so there is no need to add a link to those pages. + +Please honor the [Standards](documentation_standards.md) we have for the documentation. + +If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers. + +```text +--- +layout: page +title: "Awesome Sensor" +description: "home-assistant.io web presence" +date: 2015-06-17 08:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_release: "0.38" +ha_category: Sensor +--- + +Content...Written in markdown. + +### {% linkable_title Linkable Header %} +... +``` + +There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation. + +A couple of points to remember: + +- Document the needed steps to retrieve API keys or access token for the third party service or device if needed. +- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`. +- `ha_category:` is needed to list the platform or component in the appropriate category on the website. + +### Configuration + +Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file. + +The **Configuration Variables** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag. + +```text +{% configuration %} +api_key: + description: The API key to access the service. + required: true + type: string +name: + description: Name to use in the frontend. + required: false + default: The default name to use in the frontend. + type: string +monitored_conditions: + description: Conditions to display in the frontend. + required: true + type: list + keys: + weather: + description: A human-readable text summary. + temperature: + description: The current temperature. +{% endconfiguration %} + +``` + +Available keys: + +- **`description:`**: That the variable is about. +- **`required:`**: If the variable is required. + +```text +required: true #=> Required +required: false #=> Optional +required: inclusive #=> Inclusive +required: exclusive #=> Exclusive +required: any string here #=> Any string here +``` +- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example). +- **`default:`**: The default value for the variable. + +### 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 {% raw %}`{% endraw %}. + +When you're writing code that is to be executed on the terminal, prefix it with `$`. + +### Templates + +For the [configuration templating](https://www.home-assistant.io/docs/configuration/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](documentation_standards.md) for further details. + +If you are don't escape templates then they will be rendered and appear blank on the website. + +### HTML + +The direct usage of HTML is supported but not recommended. The note boxes are an exception. + +```html +

+ You need to enable telnet on your router. +

+``` + +### Images, icons and logos + +The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent. + +| Type | Location | +| :----------- |:----------------------------------------------| +| logos | source/images/supported_brands | +| blog | source/images/blog | +| screenshots | source/images/components | + +Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). + +### 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 `home-assistant.github.io/source/_includes/asides/docs_navigation.html`. diff --git a/docs/documentation_index.md b/docs/documentation_index.md new file mode 100644 index 00000000..33512d0f --- /dev/null +++ b/docs/documentation_index.md @@ -0,0 +1,36 @@ +--- +title: "Documentation" +--- + +The user documentation is located at [https://www.home-assistant.io](https://www.home-assistant.io). This section here is the place where we provide documentation and additional details about creating or modifying content. + +The [home-assistant.io](https://home-assistant.io) website is built using [Jekyll](http://github.com/mojombo/jekyll) and [these dependencies](https://pages.github.com/versions/). The pages are written in [Markdown](http://daringfireball.net/projects/markdown/). To add a page, you don't need to know about HTML. + +You can use the "**Edit this page on GitHub**" link to edit pages without creating a fork. Keep in mind that you can't upload images while working this way. + +For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a Pull Request (PR). + +To test your changes locally, you need to install **Ruby** and its dependencies (gems): + +- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. Ruby version 2.3.0 or higher is required. +- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` +- In your home-assistant.github.io root directory, run `$ bundle` to install the gems you need. + +Shortcut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle` + +Then you can work on the documentation: + +- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.github.io). +- Create/edit/update a page in the directory `source/_components/` for your platform/component. +- Test your changes to home-assistant.io locally: run `rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000) +- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is a new feature, platform, or component. +- Create a Pull Request (PR) against the **current** branch of home-assistant.github.io if you fix stuff, create Cookbook entries, or expand existing documentation. + +It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview. + +Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding: + +```bash +$ ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine +``` + diff --git a/docs/documentation_standards.md b/docs/documentation_standards.md new file mode 100644 index 00000000..39ca7d3b --- /dev/null +++ b/docs/documentation_standards.md @@ -0,0 +1,110 @@ +--- +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. + +## General Documentation + +* The language of the documentation should be American-English. +* Don't put two spaces after a period and avoid the "Oxford comma". +* Be objective and not gender favoring, polarizing, race related or religion inconsiderate. +* The case of brand names, services, protocols, components, and platforms must match its respective counterpart. e.g., "Z-Wave" **not** "Zwave", "Z-wave", "Z Wave" or "ZWave". Also, "Input Select" **not** "input select" or "Input select". +* All headings should use the `{% linkable_title %}` tag. + +## Component and Platform Pages + +* The **Configuration Variables** section must use the `{% configuration %}` tag. +* Configuration variables must document the requirement status. +* Configuration variables must document the default value, if any. +* Configuration variables must document the accepted value types. + * For configuration variables that accept multiple types, separate the types with a comma (i.e. `string, int`). +* Use YAML sequence syntax in the sample code if it is supported. +* 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`. + * If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note. +* Component and platform names should be a link to their respective documentation pages. + +## Templates + +* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the `{% raw %}` tag. +* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`. +* Use double quotes (`"`) for ([more information](#single-vs-double-quotation-marks)): + * `friendly_name` + * Single-line templates: + * `value_template` + * `level_template` + * `icon_template` + * Children of `data_template` +* Use single quotes (`'`) for ([more information](#single-vs-double-quotation-marks): + * Strings inside of templates: + * States + * Entity IDs + * `unit_of_measurement` +* No whitespace around pipe character (`|`) for Jinja2 filters. +* Single whitespace after Jinja2 opening delimiters ({% raw %}`{{`{% endraw %}). +* Single whitespace before Jinja2 closing delimiters ({% raw %}`}}`{% endraw %}). +* Do not quote values for: + * `device_class` + * `platform` + * `condition` + * `service` + +## Renaming Pages + +It can happen that a component or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old component/platform name, to the page in a [note](/developers/documentation/create_page/#html). + +```text +--- +... +redirect_from: /getting-started/android/ +--- +``` + +Adding a redirect also applies if you move content around in the [documentation](/docs/). + +## Single vs. Double Quotation Marks + +Use single quotes (`'`) for strings inside of a template. It is more obvious to escape a single quote when necessary (i.e. `name` is a possessive noun), because the single quotes that wrap the string are closer in position to the apostrophe inside the string. Use double quotes (`"`) outside of a template (unless it is a multi-line template, in which case outside quotes are not required). + +### Examples + +#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %} + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: "{% if trigger.to_state.name == 'Dale\'s Bedroom' %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}" +``` + +#### Single Quotes Outside, Double Quotes Inside (Invalid) + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: '{% if trigger.to_state.name == "Dale's Bedroom" %}Someone's in your base, killing your noobs!{% else %}It's just another door.{% endif %}' +``` + +#### Multi-Line Template (Valid) + + +```yaml +automation: + ... + action: + - service: notify.notify + data_template: + message: >- + {% if trigger.to_state.name == 'Dale\'s Bedroom' %} + Someone's in your base, killing your noobs! + {% else %} + It's just another door. + {% endif %} +``` + diff --git a/website/sidebars.json b/website/sidebars.json index 591782a6..c3acc477 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -115,6 +115,11 @@ "internationalization_custom_component_localization", "internationalization_translation" ], + "Documentation": [ + "documentation_index", + "documentation_standards", + "documentation_create_page" + ], "Intents": [ "intent_index", "intent_firing",