Merge pull request #574 from martinRenou/add_save

Add save to HTML method

Author: martinRenou

docs/source/api_reference/basemaps.rst

@@ -1,3 +1,5 @@
+.. _basemaps-section:
+
 Basemaps
 ========
 

docs/source/api_reference/map.rst

@@ -1,21 +1,51 @@
 Map
 ===
 
-Example
--------
+Usage
+-----
 
 .. jupyter-execute::
 
     from ipyleaflet import Map, basemaps, basemap_to_tiles
 
     m = Map(
-        layers=(basemap_to_tiles(basemaps.NASAGIBS.ModisTerraTrueColorCR, "2017-04-08"), ),
+        basemap=basemap_to_tiles(basemaps.NASAGIBS.ModisTerraTrueColorCR, "2017-04-08"),
         center=(52.204793, 360.121558),
         zoom=4
     )
 
     m
 
+You can find the list of available basemaps in the :ref:`basemaps-section` page.
+
+You can add multiple layers and controls to the map, using the ``add_layer``/``add_control`` methods. All those layers and controls are widgets themselves. So you can dynamically update their attributes from Python or by interacting with the map on the page (see :ref:`usage-section`)
+
+.. jupyter-execute::
+
+    from ipyleaflet import Map, Marker, basemaps, basemap_to_tiles
+
+    m = Map(
+        basemap=basemap_to_tiles(basemaps.NASAGIBS.ModisTerraTrueColorCR, "2017-04-08"),
+        center=(52.204793, 360.121558),
+        zoom=4
+    )
+
+    m.add_layer(Marker(location=(52.204793, 360.121558)))
+
+    m
+
+Save to HTML
+------------
+
+You can save the ``Map`` and all its layers and controls to an HTML page using the ``save`` method:
+
+.. code::
+
+    m.save('my_map.html', title='My Map')
+
+.. note::
+    The saved file is a static HTML page, so there is no possible interaction with Python anymore. This means that all the Python callbacks you defined (`e.g.` on marker move) cannot be executed. If you want to serve the ``Map`` widget to an HTML page while keeping a Python kernel alive on the server, you might want to look at `Voilà <https://voila.readthedocs.io>`_.
+
 
 Attributes
 ----------
@@ -65,4 +95,5 @@ add_control        Control instance                          Add a new control t
 remove_control     Control instance                          Remove a control from the map
 clear_controls                                               Remove all controls from the map
 on_interaction     callable object                           Add a callback on interaction
+save               output file                               Save the map to an HTML file
 ================   =====================================     ===

docs/source/usage.rst

@@ -1,3 +1,5 @@
+.. _usage-section:
+
 Usage
 =====
 

ipyleaflet/leaflet.py

@@ -12,6 +12,7 @@
 )
 
 from ipywidgets.widgets.trait_types import InstanceDict
+from ipywidgets.embed import embed_minimal_html
 
 from traitlets import (
     CFloat, Float, Unicode, Int, Tuple, List, Instance, Bool, Dict, Enum,
@@ -1181,6 +1182,18 @@ def remove_control(self, control):
     def clear_controls(self):
         self.controls = ()
 
+    def save(self, outfile, **kwargs):
+        """Save the Map to an .html file.
+
+        Parameters
+        ----------
+        outfile: str or file-like object
+            The file to write the HTML output to.
+        kwargs: keyword-arguments
+            Extra parameters to pass to the ipywidgets.embed.embed_minimal_html function.
+        """
+        embed_minimal_html(outfile, views=[self], **kwargs)
+
     def __iadd__(self, item):
         if isinstance(item, Layer):
             self.add_layer(item)