Merge pull request #678 from ocefpaf/consistent_docstring_plugins

Consistent docstring for the plugins

Author: ocefpaf

folium/plugins/__init__.py

@@ -4,7 +4,8 @@
 Folium plugins
 --------------
 
-Add different objects/effects on a folium map.
+Wrap some of the most populat leaflet external plugins.
+
 """
 
 from __future__ import (absolute_import, division, print_function)

folium/plugins/boat_marker.py

@@ -1,14 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""
-Boat marker
------------
-
-Creates a marker shaped like a boat.
-Optionally you can append a wind direction.
-
-"""
-
 from __future__ import (absolute_import, division, print_function)
 
 import json
@@ -21,28 +12,29 @@
 
 
 class BoatMarker(Marker):
-    """Adds a BoatMarker layer on the map."""
-    def __init__(self, location, popup=None, icon=None,
-                 heading=0, wind_heading=None, wind_speed=0, **kwargs):
-        """Creates a BoatMarker plugin to append into a map with
-        Map.add_plugin.
+    """
+    Creates a BoatMarker plugin to append into a map with
+    Map.add_plugin.
+
+    Parameters
+    ----------
+    location: tuple of length 2, default None
+        The latitude and longitude of the marker.
+        If None, then the middle of the map is used.
 
-        Parameters
-        ----------
-            location: tuple of length 2, default None
-                The latitude and longitude of the marker.
-                If None, then the middle of the map is used.
+    heading: int, default 0
+        Heading of the boat to an angle value between 0 and 360 degrees
 
-            heading: int, default 0
-                Heading of the boat to an angle value between 0 and 360 degrees
+    wind_heading: int, default None
+        Heading of the wind to an angle value between 0 and 360 degrees
+        If None, then no wind is represented.
 
-            wind_heading: int, default None
-                Heading of the wind to an angle value between 0 and 360 degrees
-                If None, then no wind is represented.
+    wind_speed: int, default 0
+        Speed of the wind in knots.
 
-            wind_speed: int, default 0
-                Speed of the wind in knots.
-        """
+    """
+    def __init__(self, location, popup=None, icon=None,
+                 heading=0, wind_heading=None, wind_speed=0, **kwargs):
         super(BoatMarker, self).__init__(location, popup=popup, icon=icon)
         self._name = 'BoatMarker'
         self.heading = heading

folium/plugins/fast_marker_cluster.py

@@ -1,12 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""
-Marker Cluster plugin
----------------------
-
-Creates a MarkerCluster plugin to add on a folium map.
-"""
-
 from __future__ import (absolute_import, division, print_function)
 
 from folium.plugins.marker_cluster import MarkerCluster
@@ -15,30 +8,30 @@
 
 
 class FastMarkerCluster(MarkerCluster):
-    """Add marker clusters to a map using in-browser rendering"""
+    """
+    Add marker clusters to a map using in-browser rendering.
+    Using FastMarkerCluster it is possible to render 000's of
+    points far quicker than the MarkerCluster class.
+
+    Be aware that the FastMarkerCluster class passes an empty
+    list to the parent class' __init__ method during initialisation.
+    This means that the add_child method is never called, and
+    no reference to any marker data are retained. Methods such
+    as get_bounds() are therefore not available when using it.
+
+    Parameters
+    ----------
+    data: list
+        List of list of shape [[], []]. Data points should be of
+        the form [[lat, lng]].
+
+    callback: string, default None
+        A string representation of a valid Javascript function
+        that will be passed a lat, lon coordinate pair. See the
+        FasterMarkerCluster for an example of a custom callback.
+
+    """
     def __init__(self, data, callback=None):
-        """Add marker clusters to a map using in-browser rendering.
-           Using FastMarkerCluster it is possible to render 000's of
-           points far quicker than the MarkerCluster class.
-
-           Be aware that the FastMarkerCluster class passes an empty
-           list to the parent class' __init__ method during initialisation.
-           This means that the add_child method is never called, and
-           no reference to any marker data are retained. Methods such
-           as get_bounds() are therefore not available when using it.
-
-        Parameters
-        ----------
-            data: list
-                List of list of shape [[], []]. Data points should be of
-                the form [[lat, lng]].
-
-            callback: string, default None
-                A string representation of a valid Javascript function
-                that will be passed a lat, lon coordinate pair. See the
-                FasterMarkerCluster for an example of a custom callback.
-
-        """
         super(FastMarkerCluster, self).__init__([])
         self._name = 'FastMarkerCluster'
         self._data = data

folium/plugins/float_image.py

@@ -1,12 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""
-FloatImage plugin
------------------
-
-Adds a floating image in HTML canvas on top of the map.
-"""
-
 from __future__ import (absolute_import, division, print_function)
 
 from branca.element import MacroElement
@@ -15,8 +8,8 @@
 
 
 class FloatImage(MacroElement):
+    """Adds a floating image in HTML canvas on top of the map."""
     def __init__(self, image, bottom=75, left=75):
-        """Adds a floating image in HTML canvas on top of the map."""
         super(FloatImage, self).__init__()
         self._name = 'FloatImage'
         self.image = image

folium/plugins/fullscreen.py

@@ -1,14 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""
-Fullscreen
---------------
-
-https://github.com/brunob/leaflet.fullscreen
-
-Adds fullscreen button to your maps.
-"""
-
 from __future__ import (absolute_import, division, print_function)
 
 from branca.element import CssLink, Figure, JavascriptLink, MacroElement
@@ -29,31 +20,31 @@ class Fullscreen(MacroElement):
     title : str
           change the title of the button,
           default: 'Full Screen'
-    titleCancel : str
+    title_cancel : str
           change the title of the button when fullscreen is on,
           default: 'Exit Full Screen'
-    forceSeparateButton : boolean
+    force_separate_button : boolean
           force seperate button to detach from zoom buttons,
           default: False
-    """
+    See https://github.com/brunob/leaflet.fullscreen for more information.
 
+    """
     def __init__(self, position='topleft', title='Full Screen',
-                 titleCancel='Exit Full Screen', forceSeparateButton=False):
-        """Add button to take your Folium map fullscreen"""
+                 title_cancel='Exit Full Screen', force_separate_button=False):
         super(Fullscreen, self).__init__()
         self._name = 'Fullscreen'
         self.position = position
         self.title = title
-        self.titleCancel = titleCancel
-        self.forceSeparateButton = str(forceSeparateButton).lower()
+        self.title_cancel = title_cancel
+        self.force_separate_button = str(force_separate_button).lower()
 
         self._template = Template("""
         {% macro script(this, kwargs) %}
             L.control.fullscreen({
                 position: '{{this.position}}',
                 title: '{{this.title}}',
-                titleCancel: '{{this.titleCancel}}',
-                forceSeparateButton: {{this.forceSeparateButton}},
+                titleCancel: '{{this.title_cancel}}',
+                forceSeparateButton: {{this.force_separate_button}},
                 }).addTo({{this._parent.get_name()}});
             {{this._parent.get_name()}}.on('enterFullscreen', function(){
                 console.log('entered fullscreen');

folium/plugins/heat_map.py

@@ -1,13 +1,5 @@
 # -*- coding: utf-8 -*-
 
-"""
-Heat map
---------
-
-Create a HeatMap layer
-
-"""
-
 from __future__ import (absolute_import, division, print_function)
 
 import json
@@ -21,31 +13,33 @@
 
 
 class HeatMap(TileLayer):
+    """
+    Create a Heatmap layer
+
+    Parameters
+    ----------
+    data : list of points of the form [lat, lng] or [lat, lng, weight]
+        The points you want to plot.
+        You can also provide a numpy.array of shape (n,2) or (n,3).
+    name : str
+        The name of the layer that will be created.
+    min_opacity  : default 1.
+        The minimum opacity the heat will start at.
+    max_zoom : default 18
+        Zoom level where the points reach maximum intensity (as intensity
+        scales with zoom), equals maxZoom of the map by default
+    max_val : float, default 1.
+        Maximum point intensity
+    radius : int, default 25
+        Radius of each "point" of the heatmap
+    blur : int, default 15
+        Amount of blur
+    gradient : dict, default None
+        Color gradient config. e.g. {0.4: 'blue', 0.65: 'lime', 1: 'red'}
+
+    """
     def __init__(self, data, name=None, min_opacity=0.5, max_zoom=18,
                  max_val=1.0, radius=25, blur=15, gradient=None, overlay=True):
-        """Create a Heatmap layer
-
-        Parameters
-        ----------
-        data : list of points of the form [lat, lng] or [lat, lng, weight]
-            The points you want to plot.
-            You can also provide a numpy.array of shape (n,2) or (n,3).
-        name : str
-            The name of the layer that will be created.
-        min_opacity  : default 1.
-            The minimum opacity the heat will start at.
-        max_zoom : default 18
-            Zoom level where the points reach maximum intensity (as intensity
-            scales with zoom), equals maxZoom of the map by default
-        max_val : float, default 1.
-            Maximum point intensity
-        radius : int, default 25
-            Radius of each "point" of the heatmap
-        blur : int, default 15
-            Amount of blur
-        gradient : dict, default None
-            Color gradient config. e.g. {0.4: 'blue', 0.65: 'lime', 1: 'red'}
-        """
         super(TileLayer, self).__init__(name=name)
         self._name = 'HeatMap'
         self.tile_name = name if name is not None else self.get_name()