Merge pull request #384 from martinRenou/docs

Add Usage section in the docs

Author: martinRenou

README.md

@@ -1,7 +1,7 @@
 # ipyleaflet
 
 [![Documentation](http://readthedocs.org/projects/ipyleaflet/badge/?version=latest)](https://ipyleaflet.readthedocs.io/en/latest/?badge=latest)
-[![Binder](https://img.shields.io/badge/launch-binder-brightgreen.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipyleaflet/stable?filepath=examples)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipyleaflet/stable?filepath=examples)
 [![Join the Gitter Chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 A Jupyter / Leaflet bridge enabling interactive maps in the Jupyter notebook.

docs/source/api_reference/marker.rst

@@ -9,7 +9,7 @@ Example
 
 .. code::
 
-    from ipyleaflet import Marker
+    from ipyleaflet import Map, Marker
 
     center = (52.204793, 360.121558)
 

docs/source/index.rst

@@ -7,6 +7,11 @@ ipyleaflet: Interactive maps in the Jupyter notebook
 
     installation
 
+.. toctree::
+    :caption: Usage
+
+    usage
+
 .. toctree::
     :caption: Map
     :maxdepth: 2

docs/source/usage.rst

@@ -0,0 +1,52 @@
+Usage
+=====
+
+ipyleaflet is an interactive widgets library, it is based on `ipywidgets <https://github.com/jupyter-widgets/ipywidgets/>`_.
+This means that everything in ipyleaflet (e.g. the ``Map``, ``TileLayers``, ``Markers``...) is interactive: you can dynamically update
+attributes from Python or from the Notebook interface.
+
+For example, you can create a ``Marker`` layer and interact with it:
+
+.. code::
+
+    from ipyleaflet import Map, Marker
+
+    center = (52.204793, 360.121558)
+
+    m = Map(center=center, zoom=15)
+
+    marker = Marker(location=center, draggable=True)
+    m.add_layer(marker);
+
+    display(m)
+
+    # Now that the marker is on the Map, you can drag it with your mouse,
+    # it will automatically update the `marker.location` attribute in Python
+
+    # You can also update the marker location from Python, that will update the
+    # marker location on the Map:
+    marker.location = (50, 356)
+
+`ipywidgets <https://github.com/jupyter-widgets/ipywidgets/>`_ is powered by `traitlets <https://github.com/ipython/traitlets/>`_,
+this brings an observer pattern implementation which allows you to react on widget attribute changes.
+
+For example, you can define a Python callback that will be called whenever the marker location has changed:
+
+.. code::
+
+    def on_location_changed(event):
+        # Do some computation given the new marker location, accessible from `event['new']`
+        pass
+
+    marker.observe(on_location_changed, 'location')
+
+Please check out the `traitlets documentation <https://traitlets.readthedocs.io/>`_ for more details about the observer pattern implementation.
+
+.. note::
+    Everything in ipyleaflet **is** an interactive widget, from the ``Map`` class to ``Layer`` and ``Control`` classes. This means that what we
+    achieved here with ``marker.location``, you can achieve it with ``map.zoom``, ``layer.url``, or ``heatmap.locations``
+
+You can try ipyleaflet online using binder, no need to install anything on your computer:
+
+.. image:: https://mybinder.org/badge_logo.svg
+    :target: https://mybinder.org/v2/gh/jupyter-widgets/ipyleaflet/stable?filepath=examples