From e391ddb7a1d38137c5ee57b2161174b375bd95f4 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Sun, 8 Feb 2015 15:08:41 -0800 Subject: [PATCH] Add linkable titles --- plugins/linkable_title.rb | 16 +++++++++++++++ sass/custom/_paulus.scss | 19 ++++++++++++++++++ source/developers/add_new_platform.markdown | 8 ++++---- source/developers/api.markdown | 20 +++++++++---------- source/developers/architecture.markdown | 8 ++++---- .../developers/creating_components.markdown | 8 ++++---- source/developers/frontend.markdown | 8 ++++---- source/getting-started/index.markdown | 6 +++--- 8 files changed, 64 insertions(+), 29 deletions(-) create mode 100644 plugins/linkable_title.rb diff --git a/plugins/linkable_title.rb b/plugins/linkable_title.rb new file mode 100644 index 00000000000..da677b296be --- /dev/null +++ b/plugins/linkable_title.rb @@ -0,0 +1,16 @@ +module Jekyll + class LinkableTitleTag < Liquid::Tag + def initialize(tag_name, text, token) + super + @title = text + end + + def render(context) + slug = @title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '') + + " #{@title}" + end + end +end + +Liquid::Template.register_tag('linkable_title', Jekyll::LinkableTitleTag) diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index 36f2c26b6c5..2b48d400c9f 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -2,6 +2,25 @@ // https://fortawesome.github.io/Font-Awesome/3.2.1/icons/ +h1:hover a.title-link, +h2:hover a.title-link, +h3:hover a.title-link, +h4:hover a.title-link, +h5:hover a.title-link, +h6:hover a.title-link { + position: relative; + + &::before { + position: absolute; + left: -50px; + padding-right: 40px; + font-family: "FontAwesome"; + content: "\f0c1" + } +} + +f0c1 + .ha-title { white-space: nowrap; diff --git a/source/developers/add_new_platform.markdown b/source/developers/add_new_platform.markdown index 427d08b2576..6b13420d5d9 100644 --- a/source/developers/add_new_platform.markdown +++ b/source/developers/add_new_platform.markdown @@ -26,17 +26,17 @@ Platform logic should not interface directly with the devices but use a third-pa

-## Allowing your platform to be discovered +## {% linkable_title Allowing your platform to be discovered %} Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event. -### Add discovery instructions +### {% linkable_title Add discovery instructions %} Device discovery for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/balloob/netdisco). This library is integrated using [the `discovery` component](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services. To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverables.](https://github.com/balloob/netdisco/tree/master/netdisco/discoverables) -### Listening to `SERVICE_DISCOVERED` events +### {% linkable_title Listening to `SERVICE_DISCOVERED` events %} From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts: @@ -54,7 +54,7 @@ def setup(hass, config): hass, discovery.services.GOOGLE_CAST, chromecast_discovered) ``` -### Auto-loading your component upon discovery +### {% linkable_title Auto-loading your component upon discovery %} The Discovery component is capable of setting up your components before firing the `SERVICE_DISCOVERD` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py#L29) constant in [the `discovery` component](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py). diff --git a/source/developers/api.markdown b/source/developers/api.markdown index 54b2c5592d8..54d4e39cf3f 100644 --- a/source/developers/api.markdown +++ b/source/developers/api.markdown @@ -31,7 +31,7 @@ Successful calls will return status code 200 or 201. Other status codes that can The api supports the following actions: -#### GET /api +#### {% linkable_title GET /api %} Returns message if API is up and running. ```json @@ -40,7 +40,7 @@ Returns message if API is up and running. } ``` -#### GET /api/events +#### {% linkable_title GET /api/events %} Returns an array of event objects. Each event object contain event name and listener count. ```json @@ -56,7 +56,7 @@ Returns an array of event objects. Each event object contain event name and list ] ``` -#### GET /api/services +#### {% linkable_title GET /api/services %} Returns an array of service objects. Each object contains the domain and which services it contains. ```json @@ -77,7 +77,7 @@ Returns an array of service objects. Each object contains the domain and which s ] ``` -#### GET /api/states +#### {% linkable_title GET /api/states %} Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes. ```json @@ -100,7 +100,7 @@ Returns an array of state objects. Each state has the following attributes: enti ] ``` -#### GET /api/states/<entity_id> +#### {% linkable_title GET /api/states/<entity_id> %} Returns a state object for specified entity_id. Returns 404 if not found. ```json @@ -115,7 +115,7 @@ Returns a state object for specified entity_id. Returns 404 if not found. } ``` -#### POST /api/states/<entity_id> +#### {% linkable_title POST /api/states/<entity_id> %} Updates or creates the current state of an entity. Expects a JSON object that has atleast a state attribute: @@ -142,7 +142,7 @@ Return code is 200 if the entity existed, 201 if the state of a new entity was s } ``` -#### POST /api/events/<event_type> +#### {% linkable_title POST /api/events/<event_type> %} Fires an event with event_type You can pass an optional JSON object to be used as `event_data`. @@ -161,7 +161,7 @@ Returns a message if successful. } ``` -#### POST /api/services/<domain>/<service> +#### {% linkable_title POST /api/services/<domain>/<service> %} Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first. You can pass an optional JSON object to be used as `service_data`. @@ -198,7 +198,7 @@ Returns a list of states that have changed while the service was being executed. The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.

-#### POST /api/event_forwarding +#### {% linkable_title POST /api/event_forwarding %} Setup event forwarding to another Home Assistant instance. Requires a JSON object that represents the API to forward to. @@ -219,7 +219,7 @@ It will return a message if event forwarding was setup successful. } ``` -#### DELETE /api/event_forwarding +#### {% linkable_title DELETE /api/event_forwarding %} Cancel event forwarding to another Home Assistant instance.
Requires a JSON object that represents the API to cancel forwarding to. diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index 4a85de1703c..b4641b68aec 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -42,14 +42,14 @@ Home Assistant can be extended by **components**. Each component is responsible We can differentiate between two different types of components within Home Assistant. -#### Components that interact with an Internet of Things domain +#### {% linkable_title Components that interact with an Internet of Things domain %} These components will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches. If you are planning to add support for a new platform, please check out the [add new platform section]({{root_url}}/developers/add_new_platform.html). -#### Components that respond to events that happen within Home Assistant +#### {% linkable_title Components that respond to events that happen within Home Assistant %} These components provide small pieces of home automation logic or services that do common tasks within your house. For example the `device_sun_light_trigger` component tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines: @@ -72,7 +72,7 @@ For example the `device_sun_light_trigger` component tracks the state of devices Another example of a home automation component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py). -### The full picture +### {% linkable_title The full picture %} When we put all the different pieces of Home Assistant together we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefor ommitted from the following picture. @@ -85,7 +85,7 @@ When we put all the different pieces of Home Assistant together we see that we m Component's platform logic uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community. -## Multiple connected instances +## {% linkable_title Multiple connected instances %} Home Assistant supports running multiple synchronzied instances using a master-slave model. Whenever `events.fire` or `states.set` is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves. diff --git a/source/developers/creating_components.markdown b/source/developers/creating_components.markdown index 40bb3a6967b..a3bde8ee507 100644 --- a/source/developers/creating_components.markdown +++ b/source/developers/creating_components.markdown @@ -25,7 +25,7 @@ target=TARGET_ENTITY `TARGET_ENTITY` should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be `light.Ceiling` or `switch.AC` (if you have these devices with those names). -## Loading components +## {% linkable_title Loading components %} A component will be loaded on start if a section (ie. `[light]`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: @@ -42,7 +42,7 @@ You can override a built-in component by having a component with the same name i Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.

-## Initializing components +## {% linkable_title Initializing components %} After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in: @@ -51,7 +51,7 @@ After loading, the bootstrapper will call `setup(hass, config)` method on the co | hass | The Home Assistant object. Call its methods to track time, register services, listen for events or track states: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L38) | | config | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration. | -### Guidance on using the Home Assistant object +### {% linkable_title Guidance on using the Home Assistant object %} The Home Assistant object contains three objects to help you interact with the system. | Object | Description | @@ -60,7 +60,7 @@ The Home Assistant object contains three objects to help you interact with the s | hass.events | This is the EventBus. It allows you to trigger and listen for events.
[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L308). | | hass.services | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L589). | -### Example on using the configuration parameter +### {% linkable_title Example on using the configuration parameter %} If your configuration file containes the following lines: ``` diff --git a/source/developers/frontend.markdown b/source/developers/frontend.markdown index 1e4c0066c1c..c647971e326 100644 --- a/source/developers/frontend.markdown +++ b/source/developers/frontend.markdown @@ -11,7 +11,7 @@ footer: true Home Assistant uses [Polymer](https://www.polymer-project.org/) for the frontend. Polymer allows building encapsulated and interoperable custom elements that extend HTML itself. -# Turning on development mode +# {% linkable_title Turning on development mode %} Home Assistant will by default serve the compiled version of the frontend. To change it so that the components are served separately, update your `home-assistant.conf` to have these lines: ``` @@ -26,7 +26,7 @@ After turning on development mode, you will have to install the webcomponents th Do not use development mode in production. Home Assistant uses aggresive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.

-# Building the frontend +# {% linkable_title Building the frontend %} To build the frontend you need to install node and the npm packages bower and vulcanize. @@ -36,7 +36,7 @@ npm install -g bower vulcanize After that you can run [`./build_frontend`](https://github.com/balloob/home-assistant/blob/master/build_frontend) from the project directory. This will take all the used webcomponents and 'vulcanize' it into a single file to be served by Home Assistant. The script also updates [`homeassistant/components/http/frontend.py`](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/frontend.py) with an MD5 hash of the frontend. -# Adding state cards +# {% linkable_title Adding state cards %} The main interface of Home Assistant is a list of current states in the State Machine. It will filter out the group states and offers options to filter by groups on the top. @@ -51,7 +51,7 @@ To add your own card type, follow the following steps: 2. Create a new component following the naming convention state-card-CARDTYPE.html in [/cards/](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/www_static/polymer/cards/). 3. Import your new component in [/cards/state-card-content.html](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/www_static/polymer/cards/state-card-content.html). -# More info screens for custom types +# {% linkable_title More info screens for custom types %} When you click on a card, the more info dialog will open for that card. This will allow you to see more information and more options to control that entity. diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index f3d3332f771..9491af7b125 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -40,7 +40,7 @@ If you're using Docker, you can use docker run -d --name="home-assistant" -v /path/to/homeassistant/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant ``` -## Configuring Home Assistant +## {% linkable_title Configuring Home Assistant %} The configuration for Home Assistant lives by default in the `config` folder. The file `home-assistant.conf` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example). @@ -65,7 +65,7 @@ api_password=YOUR_PASSWORD You can append ?api_password=YOUR_PASSWORD to any url to log in automatically.

-### Adding devices and services +### {% linkable_title Adding devices and services %} Home Assistant will be able to automatically discover and configure any Google Chromecasts, Belkin WeMo switches and Philips Hue bridges in your network if you have [the discovery component]({{site_root}}/components/discovery.html) enabled (which is by default). @@ -78,7 +78,7 @@ Not all devices can be discovered, so if you hae any of the following devices or * [Sun]({{site_root}}/components/sun.html) * [Add support for your own device or service]({{site_root}}/developers/add_new_platform.html) -### Setting up Home Automation +### {% linkable_title Setting up Home Automation %} When all your devices are set up it's time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics: