An effort on docstrings in plugins

Author: Martin Journois

folium/plugins/__init__.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+Folium plugins
+--------------
 
+Add different objetcs/effects on a folium map.
+"""
 from .marker_cluster import MarkerCluster
 from .scroll_zoom_toggler import ScrollZoomToggler
 from .terminator import Terminator

folium/plugins/boat_marker.py

@@ -1,11 +1,16 @@
 # -*- coding: utf-8 -*-
+"""
+Boat marker
+-----------
 
+Creates a marker shaped like a boat. Optionally you can append a wind direction. 
+"""
 import json
 
 from .plugin import Plugin
 
 class BoatMarker(Plugin):
-    """Adds a MarkerCluster layer on the map."""
+    """Adds a BoatMarker layer on the map."""
     def __init__(self, position=None, heading=0, wind_heading=None, wind_speed=0, **kwargs):
         """Creates a BoatMarker plugin to append into a map with
         Map.add_plugin.

folium/plugins/geo_json.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+GeoJson plugin
+--------------
 
+Add a geojson feature collection on a folium map.
+"""
 import json
 
 from .plugin import Plugin

folium/plugins/layer.py

@@ -1,10 +1,32 @@
 # -*- coding: utf-8 -*-
+"""
+Layer plugin
+------------
 
+Add layers and layer control to the map.
+"""
 from .plugin import Plugin
 
 class Layer(Plugin):
     """Adds a layer to the map."""
     def __init__(self, url=None, layer_name = None, min_zoom=1, max_zoom=18, attribution=''):
+        """Crates a layer object to be added on a folium map.
+        
+        Parameters
+        ----------
+            url : str
+                The url of the layer service, in the classical leaflet form.
+                    example: url='//otile1.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png'
+            layer_name : str
+                Tha name of the layer that will be displayed in the layer control.
+                If None, a random hexadecimal string will be created.
+            min_zoom : int, default 1
+                The minimal zoom allowed for this layer
+            max_zoom : int, default 18
+                The maximal zoom allowed for this layer
+            attribution : str, default ''
+                Tha atribution string for the layer.
+        """
         super(Layer, self).__init__()
         self.plugin_name = 'Layer'
         self.tile_url = url
@@ -16,6 +38,7 @@ def __init__(self, url=None, layer_name = None, min_zoom=1, max_zoom=18, attribu
             self.object_name = layer_name
 
     def render_js(self, nb):
+        """Generates the JS part of the plugin."""
         return """
         var layer_"""+self.object_id+""" = L.tileLayer('"""+self.tile_url+"""', {
             maxZoom: """+str(self.max_zoom)+""",
@@ -27,14 +50,23 @@ def render_js(self, nb):
 
 class LayerControl(Plugin):
     """Adds a layer control to the map."""
-    def __init__(self):
+    def __init__(self, base_layer_name="Base Layer"):
+        """Creates a LayerControl object to be added on a folium map.
+        
+        Parameters
+        ----------
+            base_layer_name : str, default "Base Layer"
+                The name of the base layer that you want to see on the control.
+        """
         super(LayerControl, self).__init__()
         self.plugin_name = 'LayerControl'
+        self.base_layer_name = base_layer_name
 
     def render_js(self, nb):
+        """Generates the JS part of the plugin."""
         return """
         var baseLayer = {
-          "Base Layer": base_tile,"""+\
+          "%s": base_tile,"""% self.base_layer_name+\
         ",".join(['"%s" : layer_%s ' % (x.object_name,x.object_id) for x in self.map.plugins['Layer']])+\
         """};
 

folium/plugins/marker_cluster.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+Marker Cluster plugin
+---------------------
 
+Creates a MarkerCluster plugin to add on a folium map.
+"""
 import json
 
 from .plugin import Plugin

folium/plugins/plugin.py

@@ -1,5 +1,12 @@
 # -*- coding: utf-8 -*-
+"""
+Plugin
+------
 
+A generic class for creating plugins.
+Basic plugin object that does nothing.
+Other plugins may inherit from this one.
+"""
 from uuid import uuid4
 
 class Plugin(object):

folium/plugins/scroll_zoom_toggler.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+ScrollZoomToggler plugin
+------------------------
 
+Adds a button to enable/disable zoom scrolling.
+"""
 from .template_plugin import TemplatePlugin
 
 class ScrollZoomToggler(TemplatePlugin):

folium/plugins/template_plugin.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
+"""
+Template Plugin
 
+A generic class to create plugins based on jinja2 templates.
+"""
 from .plugin import Plugin
 from jinja2 import Template
 from uuid import uuid4

folium/plugins/terminator.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
+"""
+Terminator plugin
+-----------------
 
+Leaflet.Terminator is a simple plug-in to the Leaflet library to overlay day and night regions on maps.
+"""
 try:
     from urllib.request import urlopen as _urlopen
 except: