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

Made README and website contributions match, added more detail to website contribution setup details, updated forum link, re-organised getting started and troubleshooting with respect to YAML

Browse source
This commit is contained in:
Lindsay Ward 2016-04-08 23:39:02 +10:00
parent 7fcca47d19
commit c581168e49
7 changed files with 116 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

26
source/developers/index.markdown
View file

@ -9,17 +9,20 @@ sharing: true
footer: true
---
Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Webcomponents)](https://www.polymer-project.org/) for the frontend.
Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend.
Home Assistant is open-source and MIT licensed. The source can be found here:
- [home-assistant](https://github.com/balloob/home-assistant) - Python server-backend
- [home-assistant-js](https://github.com/balloob/home-assistant-js) - javascript-backend powering the client
- [home-assistant](https://github.com/balloob/home-assistant) - Python server backend
- [home-assistant-js](https://github.com/balloob/home-assistant-js) - JavaScript backend powering the client
- [home-assistant-polymer](https://github.com/balloob/home-assistant-polymer) - Polymer UI
### {% linkable_title Starting development %}
You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to perform it. Visit the [the Home Assistant repository](https://github.com/balloob/home-assistant) first and click fork in the top right.
You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.
Visit the [the Home Assistant repository](https://github.com/balloob/home-assistant) first and click fork in the top right.
We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script.
```bash
$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
@ -28,13 +31,17 @@ $ git remote add upstream https://github.com/balloob/home-assistant.git
$ script/setup
```
We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script.
Testing your work requires `tox` to be installed:
```bash
$ pip3 install tox
```
After following these steps, running `hass` will invoke your local installation.
### {% linkable_title Submitting improvements %}
Improvements to Home Assistant should be submitted one feature at a time using Github pull requests.
Improvements to Home Assistant should be submitted one feature at a time using GitHub [pull requests](https://help.github.com/articles/using-pull-requests).
1. From your fork, create a new branch to hold your changes
`git checkout -b some-feature`
@ -44,15 +51,10 @@ Improvements to Home Assistant should be submitted one feature at a time using G
4. Commit the changes
`git add .`
`git commit -m "Added some-feature"`
5. Push your commited changes back to your fork on GitHub
5. Push your committed changes back to your fork on GitHub
`git push origin HEAD`
6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request.
Note that the above requires `tox` to be installed. If you don't have it, do this:
```bash
$ pip3 install tox
```
### {% linkable_title Further reading %}

23
source/developers/website.markdown
View file

@ -9,19 +9,28 @@ sharing: true
footer: true
---
The home of Home Assistant is [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 is using the [Octopress](http://octopress.org/) framework for [Jekyll](http://github.com/mojombo/jekyll). To get more details, please checkout the [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 alike.
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.
To work on the website the process is no different to working on Home Assistant itself.
The process for working on the website is no different from working on Home Assistant itself.
- Fork the home-assistant.io [git repository](https://github.com/balloob/home-assistant.io).
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.
Then you can work on the documentation:
- Fork home-assistant.io [git repository](https://github.com/balloob/home-assistant.io).
- Create/edit/update a page in the directory `source/_components/` for your platform/component.
- To test changes to home-assistant.io locally, run ``rake preview`` and navigate to http://127.0.0.1:4000.
- 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 **master** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
For a platform page it would be the fastest way 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 that your page.
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.
@ -37,7 +46,7 @@ If you want to display line numbers, add the following snippet somewhere on your
```
### {% linkable_title Images, icons, and logos %}
The images which are displayed on the pages are stored in various directories according their purpose.
The images which are displayed on the pages are stored in various directories according to their purpose.
| Type | Location |
| :----------- |:----------------------------------------------|