jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge remote-tracking branch 'upstream/current' into next

Browse source
This commit is contained in:
Robbie Trencheny 2016-08-27 20:56:42 -07:00
commit 9e4330bed8
108 changed files with 3083 additions and 105 deletions
Download patch file Download diff file Expand all files Collapse all files

2
source/developers/development_checklist.markdown
View file

@ -15,5 +15,5 @@ After you finish your work:
- Check that all dependencies are included via the `REQUIREMENTS` variable in your platform/component and only imported inside functions that use them.
- Add any new dependencies to `requirements_all.txt` if needed. Use `script/gen_requirements_all.py`.
- Update the `.coveragerc` file to exclude your platform if there are no tests available or your new code uses a 3rd party library for communication with the device/service/sensor.
- Provide some documentation for [home-assistant.io](https://home-assistant.io/). It's OK to just add a docstring with configuration details (sample entry for `configuration.yaml` file and alike) to the file header as a start. Visit the [website documentation](/developers/website/) for further information on contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.io).
- Provide some documentation for [home-assistant.io](https://home-assistant.io/). It's OK to just add a docstring with configuration details (sample entry for `configuration.yaml` file and alike) to the file header as a start. Visit the [website documentation](/developers/website/) for further information on contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io).

6
source/developers/development_testing.markdown
View file

@ -41,6 +41,12 @@ $ pylint homeassistant/core.py
$ py.test tests/test_core.py
```
You also run linting tests against all changed files, as reported by `git diff upstream/dev --name-only` using the `lint` script:
```bash
home-assistant$ script/lint --changed
```
### {% linkable_title Prevent Linter Errors %}
You can save yourself the hassle of extra commits just to fix style errors by enabling the flake8 git commit hook. It will check your code when you attempt to commit to the repository. It will block the commit if there are any style issues, giving you a chance to fix it.

6
source/developers/releasing.markdown
View file

@ -25,9 +25,9 @@ This page describes the steps for publishing a new Home Assistant release.
1. Create a blog post in `next` and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in message to documentation.
2. Create missing documentation as stumbs in `next`.
3. Update the link on the frontpage (`source/index.html`) to link to the new release blog post and version number.
4. Create a pull request from `next` to `master` with the upcoming release number as title.
5. Merge `master` into `next` (`$ git checkout next && git merge master`) to make the PR mergable.
6. Merge pull request (blog post, updated frontpage, and all new documentation) to `master`.
4. Create a pull request from `next` to `current` with the upcoming release number as title.
5. Merge `current` into `next` (`$ git checkout next && git merge master`) to make the PR mergable.
6. Merge pull request (blog post, updated frontpage, and all new documentation) to `current`.
### {% linkable_title Python Package Index %}

2
source/developers/server_sent_events.markdown
View file

@ -31,7 +31,7 @@ For more comfort put the HTML snippet below in a file `sse.html` in your `www` f
<h1>Getting Home Assistant server events</h1>
<div id="events"></div>
<script type="text/javascript">
var source = new EventSource("/api/stream?password=YOUR_PASSWORD");
var source = new EventSource("/api/stream?api_password=YOUR_PASSWORD");
source.onmessage = function(event) {
document.getElementById("events").innerHTML += event.data + "<br>";
};

80
source/developers/website.markdown
View file

@ -9,49 +9,89 @@ sharing: true
footer: true
---
The website you're reading now is the home of Home Assistant: [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers.
The website you're reading now is the home of Home Assistant: [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers.
home-assistant.io uses the [Octopress](http://octopress.org/) framework for [Jekyll](http://github.com/mojombo/jekyll). To get more details, please checkout the [Octopress documentation](http://octopress.org/docs/).
That means that creating a new page is simple. The pages are written in [markdown](http://daringfireball.net/projects/markdown/); you don't need to care about HTML or the like.
home-assistant.io is built using [Jekyll](http://github.com/mojombo/jekyll). The pages are written in [markdown](http://daringfireball.net/projects/markdown/); to add a page you don't need to know about HTML or the like.
The process for working on the website is no different from working on Home Assistant itself.
The link "**Edit this page on GitHub**" allows one to edit pages without creating a fork.
For larger changes, we suggest that you clone the website repository. This has the advantage that 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.
To test your changes locally, you need to install the **Ruby** dependencies (gems):
- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
- Install `bundler`, which is a dependency manager for Ruby: `gem install bundler`
- In your home-assistant.io root directory, run `bundle` to install the gems you need.
- In your home-assistant.github.io root directory, run `bundle` to install the gems you need.
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.io if your documentation is for a new feature, platform, or component.
- Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
- 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 for 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.
For a platform page, the fastest way is to make a copy of an existing page and edit it. The [component overview](/components/) is generated automatically, so there is no need to add a link to your page.
### {% linkable_title Code %}
To take advantage of the built-in features of Octopress to display code snippets, just use the default markdown syntax. Please use `$` and `#` if it's a command and to differ from output.
### {% linkable_title Create a page %}
```bash
Here goes the code...
For a platform page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](/components/) and the [Examples section](/cookbook/) are generated automatically, so there is no need to add a link to those pages.
If you start from scratch with a page, you need to add a header. Different sections of the doumentation may need different headers.
```text
---
layout: page
title: "Website home-assistant.io"
description: "home-assistant.io web presence"
date: 2015-06-17 08:00
sidebar: true
comments: false
sharing: true
footer: true
---
Content...Written in markdown.
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
...
```
If you want to display line numbers, add the following snippet somewhere on your page.
There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually it's not necessary to use them when writing documentation.
### {% linkable_title Embedding Code %}
You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in \`. For multi line syntax wrap your code as shown below.
```text
{% raw %} ```yaml
sensor:
platform: template
```{% endraw %}
```
{::options coderay_line_numbers="table" /}
If you are using templates then those parts needs to be [escaped](http://stackoverflow.com/a/24102537). Otherwise they will be rendered and appear blank on the website.
Note that you can replace `yaml` next to \`\`\` with the language that is within the block.
When you're writing code that is to be executed on the terminal, prefix it with `$`.
### {% linkable_title HTML %}
The direct usage of HTML is supported but not recommanded. The note boxes are an exception.
```html
<p class='note warning'>
You need to enable telnet on your router.
</p>
```
### {% linkable_title Images, icons, and logos %}
The images which are displayed on the pages are stored in various directories according to their purpose.
The images which are displayed on the pages are stored in various directories according to their purpose.
| Type | Location |
| :----------- |:----------------------------------------------|
| screen shots | source/images/screenshots |
| screenshots | source/images/screenshots |
| logos | source/images/supported_brands |
Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).
Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).