Add link to docs and modify docstrings to match PEP257

homeassistant/components/alarm_control_panel/demo.py

@@ -1,13 +1,14 @@
 """
-homeassistant.components.alarm_control_panel.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Demo platform that has two fake alarm control panels.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 import homeassistant.components.alarm_control_panel.manual as manual
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the Demo alarm control panels. """
+    """Setup the Demo alarm control panel platform."""
     add_devices([
         manual.ManualAlarm(hass, 'Alarm', '1234', 5, 10),
     ])

homeassistant/components/binary_sensor/demo.py

@@ -1,11 +1,14 @@
 """
 Demo platform that has two fake binary sensors.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.binary_sensor import BinarySensorDevice
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """Sets up the Demo binary sensors """
+    """Setup the Demo binary sensor platform."""
     add_devices([
         DemoBinarySensor('Basement Floor Wet', False, 'moisture'),
         DemoBinarySensor('Movement Backyard', True, 'motion'),
@@ -14,7 +17,6 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 class DemoBinarySensor(BinarySensorDevice):
     """A Demo binary sensor."""
-
     def __init__(self, name, state, sensor_class):
         self._name = name
         self._state = state
@@ -32,10 +34,10 @@ class DemoBinarySensor(BinarySensorDevice):
 
     @property
     def name(self):
-        """Returns the name of the binary sensor."""
+        """Return the name of the binary sensor."""
         return self._name
 
     @property
     def is_on(self):
-        """True if the binary sensor is on."""
+        """Return true if the binary sensor is on."""
         return self._state

homeassistant/components/camera/demo.py

@@ -1,7 +1,8 @@
 """
-homeassistant.components.camera.demo
+Demo camera platform that has a fake camera.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
-Demo platform that has a fake camera.
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 import os
 
@@ -10,21 +11,21 @@ from homeassistant.components.camera import Camera
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the Demo camera. """
+    """Setup the Demo camera platform."""
     add_devices([
         DemoCamera('Demo camera')
     ])
 
 
 class DemoCamera(Camera):
-    """ A Demo camera. """
+    """A Demo camera."""
 
     def __init__(self, name):
         super().__init__()
         self._name = name
 
     def camera_image(self):
-        """ Return a faked still image response. """
+        """Return a faked still image response."""
         now = dt_util.utcnow()
 
         image_path = os.path.join(os.path.dirname(__file__),
@@ -34,5 +35,5 @@ class DemoCamera(Camera):
 
     @property
     def name(self):
-        """ Return the name of this device. """
+        """Return the name of this camera."""
         return self._name

homeassistant/components/demo.py

@@ -1,8 +1,8 @@
 """
-homeassistant.components.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Sets up a demo environment that mimics interaction with devices.
+
+For more details about this component, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 import time
 
@@ -33,7 +33,7 @@ COMPONENTS_WITH_DEMO_PLATFORM = [
 
 
 def setup(hass, config):
-    """ Setup a demo environment. """
+    """Setup a demo environment."""
     group = loader.get_component('group')
     configurator = loader.get_component('configurator')
 
@@ -116,7 +116,7 @@ def setup(hass, config):
     configurator_ids = []
 
     def hue_configuration_callback(data):
-        """ Fake callback, mark config as done. """
+        """Fake callback, mark config as done."""
         time.sleep(2)
 
         # First time it is called, pretend it failed.

homeassistant/components/garage_door/demo.py

@@ -30,20 +30,20 @@ class DemoGarageDoor(GarageDoorDevice):
 
     @property
     def name(self):
-        """Returns the name of the device if any."""
+        """Return the name of the device if any."""
         return self._name
 
     @property
     def is_closed(self):
-        """True if device is closed."""
+        """Return true if garage door is closed."""
         return self._state == STATE_CLOSED
 
     def close_door(self, **kwargs):
-        """Close the device."""
+        """Close the garage door."""
         self._state = STATE_CLOSED
         self.update_ha_state()
 
     def open_door(self, **kwargs):
-        """Open the device."""
+        """Open the garage door."""
         self._state = STATE_OPEN
         self.update_ha_state()

homeassistant/components/light/demo.py

@@ -1,8 +1,8 @@
 """
-homeassistant.components.light.demo
+Demo light platform that implements lights.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Demo platform that implements lights.
 
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 import random
 
@@ -18,7 +18,7 @@ LIGHT_TEMPS = [240, 380]
 
 
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return demo lights. """
+    """Setup demo light platform."""
     add_devices_callback([
         DemoLight("Bed Light", False),
         DemoLight("Ceiling Lights", True, LIGHT_COLORS[0], LIGHT_TEMPS[1]),
@@ -27,7 +27,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class DemoLight(Light):
-    """ Provides a demo switch. """
+    """Provides a demo light."""
     # pylint: disable=too-many-arguments
     def __init__(self, name, state, rgb=None, ct=None, brightness=180):
         self._name = name
@@ -38,36 +38,36 @@ class DemoLight(Light):
 
     @property
     def should_poll(self):
-        """ No polling needed for a demo light. """
+        """No polling needed for a demo light."""
         return False
 
     @property
     def name(self):
-        """ Returns the name of the device if any. """
+        """Return the name of the light if any."""
         return self._name
 
     @property
     def brightness(self):
-        """ Brightness of this light between 0..255. """
+        """Return the brightness of this light between 0..255."""
         return self._brightness
 
     @property
     def rgb_color(self):
-        """ rgb color value. """
+        """Return the RBG color value."""
         return self._rgb
 
     @property
     def color_temp(self):
-        """ CT color temperature. """
+        """Return the CT color temperature."""
         return self._ct
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if light is on."""
         return self._state
 
     def turn_on(self, **kwargs):
-        """ Turn the device on. """
+        """Turn the light on."""
         self._state = True
 
         if ATTR_RGB_COLOR in kwargs:
@@ -82,6 +82,6 @@ class DemoLight(Light):
         self.update_ha_state()
 
     def turn_off(self, **kwargs):
-        """ Turn the device off. """
+        """Turn the light off."""
         self._state = False
         self.update_ha_state()

homeassistant/components/lock/demo.py

@@ -1,8 +1,8 @@
 """
-homeassistant.components.lock.demo
+Demo lock platform that has two fake locks.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Demo platform that has two fake locks.
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.lock import LockDevice
 from homeassistant.const import STATE_LOCKED, STATE_UNLOCKED
@@ -10,7 +10,7 @@ from homeassistant.const import STATE_LOCKED, STATE_UNLOCKED
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return demo locks. """
+    """Setup the demo lock platform. """
     add_devices_callback([
         DemoLock('Front Door', STATE_LOCKED),
         DemoLock('Kitchen Door', STATE_UNLOCKED)
@@ -18,32 +18,32 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class DemoLock(LockDevice):
-    """ Provides a demo lock. """
+    """Provides a demo lock."""
     def __init__(self, name, state):
         self._name = name
         self._state = state
 
     @property
     def should_poll(self):
-        """ No polling needed for a demo lock. """
+        """No polling needed for a demo lock."""
         return False
 
     @property
     def name(self):
-        """ Returns the name of the device if any. """
+        """Return the name of the lock if any."""
         return self._name
 
     @property
     def is_locked(self):
-        """ True if device is locked. """
+        """Return true if lock is locked."""
         return self._state == STATE_LOCKED
 
     def lock(self, **kwargs):
-        """ Lock the device. """
+        """Lock the device."""
         self._state = STATE_LOCKED
         self.update_ha_state()
 
     def unlock(self, **kwargs):
-        """ Unlock the device. """
+        """Unlock the device."""
         self._state = STATE_UNLOCKED
         self.update_ha_state()

homeassistant/components/media_player/demo.py

@@ -1,7 +1,8 @@
 """
-homeassistant.components.media_player.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Demo implementation of the media player.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.media_player import (
     MEDIA_TYPE_MUSIC, MEDIA_TYPE_TVSHOW, MEDIA_TYPE_VIDEO, SUPPORT_NEXT_TRACK,
@@ -13,7 +14,7 @@ from homeassistant.const import STATE_OFF, STATE_PAUSED, STATE_PLAYING
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the cast platform. """
+    """Setup the media palyer demo platform."""
     add_devices([
         DemoYoutubePlayer(
             'Living Room', 'eyU3bRy2x44',
@@ -38,10 +39,9 @@ NETFLIX_PLAYER_SUPPORT = \
 
 
 class AbstractDemoPlayer(MediaPlayerDevice):
-    """ Base class for demo media players. """
+    """A demo media players"""
     # We only implement the methods that we support
     # pylint: disable=abstract-method
-
     def __init__(self, name):
         self._name = name
         self._player_state = STATE_PLAYING
@@ -50,65 +50,64 @@ class AbstractDemoPlayer(MediaPlayerDevice):
 
     @property
     def should_poll(self):
-        """ We will push an update after each command. """
+        """Push an update after each command."""
         return False
 
     @property
     def name(self):
-        """ Name of the media player. """
+        """Return the name of the media player."""
         return self._name
 
     @property
     def state(self):
-        """ State of the player. """
+        """Return the state of the player."""
         return self._player_state
 
     @property
     def volume_level(self):
-        """ Volume level of the media player (0..1). """
+        """Return the volume level of the media player (0..1)."""
         return self._volume_level
 
     @property
     def is_volume_muted(self):
-        """ Boolean if volume is currently muted. """
+        """Return boolean if volume is currently muted."""
         return self._volume_muted
 
     def turn_on(self):
-        """ turn the media player on. """
+        """Turn the media player on."""
         self._player_state = STATE_PLAYING
         self.update_ha_state()
 
     def turn_off(self):
-        """ turn the media player off. """
+        """Turn the media player off."""
         self._player_state = STATE_OFF
         self.update_ha_state()
 
     def mute_volume(self, mute):
-        """ mute the volume. """
+        """Mute the volume."""
         self._volume_muted = mute
         self.update_ha_state()
 
     def set_volume_level(self, volume):
-        """ set volume level, range 0..1. """
+        """Set the volume level, range 0..1."""
         self._volume_level = volume
         self.update_ha_state()
 
     def media_play(self):
-        """ Send play commmand. """
+        """Send play command."""
         self._player_state = STATE_PLAYING
         self.update_ha_state()
 
     def media_pause(self):
-        """ Send pause command. """
+        """Send pause command."""
         self._player_state = STATE_PAUSED
         self.update_ha_state()
 
 
 class DemoYoutubePlayer(AbstractDemoPlayer):
-    """ A Demo media player that only supports YouTube. """
+    """A Demo media player that only supports YouTube."""
     # We only implement the methods that we support
     # pylint: disable=abstract-method
-
     def __init__(self, name, youtube_id=None, media_title=None):
         super().__init__(name)
         self.youtube_id = youtube_id
@@ -116,50 +115,49 @@ class DemoYoutubePlayer(AbstractDemoPlayer):
 
     @property
     def media_content_id(self):
-        """ Content ID of current playing media. """
+        """Return the content ID of current playing media."""
         return self.youtube_id
 
     @property
     def media_content_type(self):
-        """ Content type of current playing media. """
+        """Return the content type of current playing media."""
         return MEDIA_TYPE_VIDEO
 
     @property
     def media_duration(self):
-        """ Duration of current playing media in seconds. """
+        """ Return the duration of current playing media in seconds."""
         return 360
 
     @property
     def media_image_url(self):
-        """ Image url of current playing media. """
+        """Return the image url of current playing media."""
         return YOUTUBE_COVER_URL_FORMAT.format(self.youtube_id)
 
     @property
     def media_title(self):
-        """ Title of current playing media. """
+        """Return the title of current playing media."""
         return self._media_title
 
     @property
     def app_name(self):
-        """ Current running app. """
+        """Return the current running application."""
         return "YouTube"
 
     @property
     def supported_media_commands(self):
-        """ Flags of media commands that are supported. """
+        """Flags of media commands that are supported."""
         return YOUTUBE_PLAYER_SUPPORT
 
     def play_media(self, media_type, media_id):
-        """ Plays a piece of media. """
+        """Play a piece of media."""
         self.youtube_id = media_id
         self.update_ha_state()
 
 
 class DemoMusicPlayer(AbstractDemoPlayer):
-    """ A Demo media player that only supports YouTube. """
+    """A Demo media player that only supports YouTube."""
     # We only implement the methods that we support
     # pylint: disable=abstract-method
-
     tracks = [
         ('Technohead', 'I Wanna Be A Hippy (Flamman & Abraxas Radio Mix)'),
         ('Paul Elstak', 'Luv U More'),
@@ -188,48 +186,50 @@ class DemoMusicPlayer(AbstractDemoPlayer):
 
     @property
     def media_content_id(self):
-        """ Content ID of current playing media. """
+        """Return the content ID of current playing media."""
         return 'bounzz-1'
 
     @property
     def media_content_type(self):
-        """ Content type of current playing media. """
+        """Return the content type of current playing media."""
         return MEDIA_TYPE_MUSIC
 
     @property
     def media_duration(self):
-        """ Duration of current playing media in seconds. """
+        """Return the duration of current playing media in seconds."""
         return 213
 
     @property
     def media_image_url(self):
-        """ Image url of current playing media. """
+        """Return the image url of current playing media."""
         return 'https://graph.facebook.com/107771475912710/picture'
 
     @property
     def media_title(self):
-        """ Title of current playing media. """
+        """Return the title of current playing media."""
         return self.tracks[self._cur_track][1]
 
     @property
     def media_artist(self):
-        """ Artist of current playing media. (Music track only) """
+        """Return the artist of current playing media (Music track only)."""
         return self.tracks[self._cur_track][0]
 
     @property
     def media_album_name(self):
-        """ Album of current playing media. (Music track only) """
+        """Return the album of current playing media (Music track only)."""
         # pylint: disable=no-self-use
         return "Bounzz"
 
     @property
     def media_track(self):
-        """ Track number of current playing media. (Music track only) """
+        """
+        Return the track number of current playing media (Music track only).
+        """
         return self._cur_track + 1
 
     @property
     def supported_media_commands(self):
-        """ Flags of media commands that are supported. """
+        """Flags of media commands that are supported."""
         support = MUSIC_PLAYER_SUPPORT
 
         if self._cur_track > 0:
@@ -241,23 +241,22 @@ class DemoMusicPlayer(AbstractDemoPlayer):
         return support
 
     def media_previous_track(self):
-        """ Send previous track command. """
+        """Send previous track command."""
         if self._cur_track > 0:
             self._cur_track -= 1
             self.update_ha_state()
 
     def media_next_track(self):
-        """ Send next track command. """
+        """Send next track command."""
         if self._cur_track < len(self.tracks)-1:
             self._cur_track += 1
             self.update_ha_state()
 
 
 class DemoTVShowPlayer(AbstractDemoPlayer):
-    """ A Demo media player that only supports YouTube. """
+    """A Demo media player that only supports YouTube."""
     # We only implement the methods that we support
     # pylint: disable=abstract-method
-
     def __init__(self):
         super().__init__('Lounge room')
         self._cur_episode = 1
@@ -265,52 +264,52 @@ class DemoTVShowPlayer(AbstractDemoPlayer):
 
     @property
     def media_content_id(self):
-        """ Content ID of current playing media. """
+        """Return the content ID of current playing media."""
         return 'house-of-cards-1'
 
     @property
     def media_content_type(self):
-        """ Content type of current playing media. """
+        """Return the content type of current playing media."""
         return MEDIA_TYPE_TVSHOW
 
     @property
     def media_duration(self):
-        """ Duration of current playing media in seconds. """
+        """Return the duration of current playing media in seconds."""
         return 3600
 
     @property
     def media_image_url(self):
-        """ Image url of current playing media. """
+        """Return the image url of current playing media."""
         return 'https://graph.facebook.com/HouseofCards/picture'
 
     @property
     def media_title(self):
-        """ Title of current playing media. """
+        """Return the title of current playing media."""
         return 'Chapter {}'.format(self._cur_episode)
 
     @property
     def media_series_title(self):
-        """ Series title of current playing media. (TV Show only)"""
+        """Return the series title of current playing media (TV Show only)."""
         return 'House of Cards'
 
     @property
     def media_season(self):
-        """ Season of current playing media. (TV Show only) """
+        """Return the season of current playing media (TV Show only)."""
         return 1
 
     @property
     def media_episode(self):
-        """ Episode of current playing media. (TV Show only) """
+        """Return the episode of current playing media (TV Show only)."""
         return self._cur_episode
 
     @property
     def app_name(self):
-        """ Current running app. """
+        """Return the current running application."""
         return "Netflix"
 
     @property
     def supported_media_commands(self):
-        """ Flags of media commands that are supported. """
+        """Flag of media commands that are supported."""
         support = NETFLIX_PLAYER_SUPPORT
 
         if self._cur_episode > 1:
@@ -322,13 +321,13 @@ class DemoTVShowPlayer(AbstractDemoPlayer):
         return support
 
     def media_previous_track(self):
-        """ Send previous track command. """
+        """Send previous track command."""
         if self._cur_episode > 1:
             self._cur_episode -= 1
             self.update_ha_state()
 
     def media_next_track(self):
-        """ Send next track command. """
+        """Send next track command."""
         if self._cur_episode < self._episode_count:
             self._cur_episode += 1
             self.update_ha_state()

homeassistant/components/notify/demo.py

@@ -1,8 +1,8 @@
 """
-homeassistant.components.notify.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Demo notification service.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.notify import ATTR_TITLE, BaseNotificationService
 
@@ -10,15 +10,13 @@ EVENT_NOTIFY = "notify"
 
 
 def get_service(hass, config):
-    """ Get the demo notification service. """
+    """Get the demo notification service."""
-
     return DemoNotificationService(hass)
 
 
 # pylint: disable=too-few-public-methods
 class DemoNotificationService(BaseNotificationService):
-    """ Implements demo notification service. """
+    """Implements demo notification service."""
-
     def __init__(self, hass):
         self.hass = hass
 

homeassistant/components/rollershutter/demo.py

@@ -1,7 +1,8 @@
 """
-homeassistant.components.rollershutter.demo
+Demo platform for the rollor shutter component.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
-Demo platform for the rollorshutter component.
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.rollershutter import RollershutterDevice
 from homeassistant.const import EVENT_TIME_CHANGED
@@ -9,7 +10,7 @@ from homeassistant.helpers.event import track_utc_time_change
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the Demo rollershutters. """
+    """Setup the Demo roller shutters."""
     add_devices([
         DemoRollershutter(hass, 'Kitchen Window', 0),
         DemoRollershutter(hass, 'Living Room Window', 100),
@@ -17,9 +18,8 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 
 class DemoRollershutter(RollershutterDevice):
-    """ Represents a rollershutter.. """
+    """Represents a roller shutter."""
     # pylint: disable=no-self-use
-
     def __init__(self, hass, name, position):
         self.hass = hass
         self._name = name
@@ -29,21 +29,21 @@ class DemoRollershutter(RollershutterDevice):
 
     @property
     def name(self):
-        """ Returns the name of the rollershutter. """
+        """Returns the name of the roller shutter."""
         return self._name
 
     @property
     def should_poll(self):
-        """ No polling needed for a demo rollershutter. """
+        """No polling needed for a demo roller shutter."""
         return False
 
     @property
     def current_position(self):
-        """ Returns the current position of the rollershutter. """
+        """Return the current position of the roller shutter."""
         return self._position
 
     def move_up(self, **kwargs):
-        """ Move the rollershutter down. """
+        """Move the roller shutter down."""
         if self._position == 0:
             return
 
@@ -51,7 +51,7 @@ class DemoRollershutter(RollershutterDevice):
         self._moving_up = True
 
     def move_down(self, **kwargs):
-        """ Move the rollershutter up. """
+        """Move the roller shutter up."""
         if self._position == 100:
             return
 
@@ -59,19 +59,19 @@ class DemoRollershutter(RollershutterDevice):
         self._moving_up = False
 
     def stop(self, **kwargs):
-        """ Stop the rollershutter. """
+        """Stops the roller shutter."""
         if self._listener is not None:
             self.hass.bus.remove_listener(EVENT_TIME_CHANGED, self._listener)
             self._listener = None
 
     def _listen(self):
-        """ Listens for changes. """
+        """Listen for changes."""
         if self._listener is None:
             self._listener = track_utc_time_change(self.hass,
                                                    self._time_changed)
 
     def _time_changed(self, now):
-        """ Track time changes. """
+        """Track time changes."""
         if self._moving_up:
             self._position -= 10
         else:

homeassistant/components/sensor/demo.py

@@ -1,5 +1,8 @@
 """
 Demo platform that has a couple of fake sensors.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.const import ATTR_BATTERY_LEVEL, TEMP_CELCIUS
 from homeassistant.helpers.entity import Entity
@@ -29,22 +32,22 @@ class DemoSensor(Entity):
 
     @property
     def name(self):
-        """Returns the name of the sensor."""
+        """Return the name of the sensor."""
         return self._name
 
     @property
     def state(self):
-        """Returns the state of the sensor."""
+        """Return the state of the sensor."""
         return self._state
 
     @property
     def unit_of_measurement(self):
-        """Unit this state is expressed in."""
+        """Return the unit this state is expressed in."""
         return self._unit_of_measurement
 
     @property
     def device_state_attributes(self):
-        """Returns the state attributes."""
+        """Return the state attributes."""
         if self._battery:
             return {
                 ATTR_BATTERY_LEVEL: self._battery,

homeassistant/components/switch/demo.py

@@ -1,8 +1,8 @@
 """
-homeassistant.components.switch.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Demo platform that has two fake switches.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.switch import SwitchDevice
 from homeassistant.const import DEVICE_DEFAULT_NAME
@@ -10,7 +10,7 @@ from homeassistant.const import DEVICE_DEFAULT_NAME
 
 # pylint: disable=unused-argument
 def setup_platform(hass, config, add_devices_callback, discovery_info=None):
-    """ Find and return demo switches. """
+    """Setup the demo switches."""
     add_devices_callback([
         DemoSwitch('Decorative Lights', True, None, True),
         DemoSwitch('AC', False, 'mdi:air-conditioner', False)
@@ -18,7 +18,7 @@ def setup_platform(hass, config, add_devices_callback, discovery_info=None):
 
 
 class DemoSwitch(SwitchDevice):
-    """ Provides a demo switch. """
+    """Provide a demo switch."""
     def __init__(self, name, state, icon, assumed):
         self._name = name or DEVICE_DEFAULT_NAME
         self._state = state
@@ -27,17 +27,17 @@ class DemoSwitch(SwitchDevice):
 
     @property
     def should_poll(self):
-        """ No polling needed for a demo switch. """
+        """No polling needed for a demo switch."""
         return False
 
     @property
     def name(self):
-        """ Returns the name of the device if any. """
+        """Return the name of the device if any."""
         return self._name
 
     @property
     def icon(self):
-        """ Returns the icon to use for device if any. """
+        """Return the icon to use for device if any."""
         return self._icon
 
     @property
@@ -47,26 +47,26 @@ class DemoSwitch(SwitchDevice):
 
     @property
     def current_power_mwh(self):
-        """ Current power usage in mwh. """
+        """Returns the current power usage in mwh."""
         if self._state:
             return 100
 
     @property
     def today_power_mw(self):
-        """ Today total power usage in mw. """
+        """Return the today total power usage in mw."""
         return 1500
 
     @property
     def is_on(self):
-        """ True if device is on. """
+        """Return true if switch is on."""
         return self._state
 
     def turn_on(self, **kwargs):
-        """ Turn the device on. """
+        """Turn the switch on."""
         self._state = True
         self.update_ha_state()
 
     def turn_off(self, **kwargs):
-        """ Turn the device off. """
+        """Turn the device off."""
         self._state = False
         self.update_ha_state()

homeassistant/components/thermostat/demo.py

@@ -1,15 +1,15 @@
 """
-homeassistant.components.thermostat.demo
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Demo platform that offers a fake thermostat.
+
+For more details about this platform, please refer to the documentation
+https://home-assistant.io/components/demo/
 """
 from homeassistant.components.thermostat import ThermostatDevice
 from homeassistant.const import TEMP_CELCIUS, TEMP_FAHRENHEIT
 
 
 def setup_platform(hass, config, add_devices, discovery_info=None):
-    """ Sets up the Demo thermostats. """
+    """Setup the Demo thermostats."""
     add_devices([
         DemoThermostat("Nest", 21, TEMP_CELCIUS, False, 19),
         DemoThermostat("Thermostat", 68, TEMP_FAHRENHEIT, True, 77),
@@ -18,8 +18,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
 
 # pylint: disable=too-many-arguments
 class DemoThermostat(ThermostatDevice):
-    """ Represents a HeatControl thermostat. """
+    """Represents a HeatControl thermostat."""
-
     def __init__(self, name, target_temperature, unit_of_measurement,
                  away, current_temperature):
         self._name = name
@@ -30,42 +29,42 @@ class DemoThermostat(ThermostatDevice):
 
     @property
     def should_poll(self):
-        """ No polling needed for a demo thermostat. """
+        """No polling needed for a demo thermostat."""
         return False
 
     @property
     def name(self):
-        """ Returns the name. """
+        """Return the thermostat."""
         return self._name
 
     @property
     def unit_of_measurement(self):
-        """ Returns the unit of measurement. """
+        """Return the unit of measurement."""
         return self._unit_of_measurement
 
     @property
     def current_temperature(self):
-        """ Returns the current temperature. """
+        """Return the current temperature."""
         return self._current_temperature
 
     @property
     def target_temperature(self):
-        """ Returns the temperature we try to reach. """
+        """Return the temperature we try to reach."""
         return self._target_temperature
 
     @property
     def is_away_mode_on(self):
-        """ Returns if away mode is on. """
+        """Return if away mode is on."""
         return self._away
 
     def set_temperature(self, temperature):
-        """ Set new target temperature. """
+        """Set new target temperature."""
         self._target_temperature = temperature
 
     def turn_away_mode_on(self):
-        """ Turns away mode on. """
+        """Turn away mode on."""
         self._away = True
 
     def turn_away_mode_off(self):
-        """ Turns away mode off. """
+        """Turn away mode off."""
         self._away = False