Merge pull request plotly#492 from plotly/cdn-options

Kevin Yan · Kevin Yan · commit ef9f4ba805a1 · 2016-05-31T10:40:17.000-04:00
Updating cdn-options PR
diff --git a/plotly/offline/offline.py b/plotly/offline/offline.py
@@ -30,7 +30,6 @@
     _matplotlib_imported = False
 
 __PLOTLY_OFFLINE_INITIALIZED = False
-__PLOTLY_USE_CDN = False
 
 
 def download_plotlyjs(download_url):
@@ -53,14 +52,31 @@ def init_notebook_mode(connected=False):
     Initialize plotly.js in the browser if it hasn't been loaded into the DOM
     yet. This is an idempotent method and can and should be called from any
     offline methods that require plotly.js to be loaded into the notebook dom.
+
+    Keyword arguments:
+
+    connected (default=False) -- If True, the plotly.js library will be loaded
+    from an online CDN. If False, the plotly.js library will be loaded locally
+    from the plotly python package
+
+    Use `connected=True` if you want your notebooks to have smaller file sizes.
+    In the case where `connected=False`, the entirety of the plotly.js library
+    will be loaded into the notebook, which will result in a file-size increase
+    of a couple megabytes. Additionally, because the library will be downloaded
+    from the web, you and your viewers must be connected to the internet to be
+    able to view charts within this notebook.
+
+    Use `connected=False` if you want you and your collaborators to be able to
+    create and view these charts regardless of the availability of an internet
+    connection. This is the default option since it is the most predictable.
+    Note that under this setting the library will be included inline inside
+    your notebook, resulting in much larger notebook sizes compared to the case
+    where `connected=True`.
     """
     if not _ipython_imported:
         raise ImportError('`iplot` can only run inside an IPython Notebook.')
 
     global __PLOTLY_OFFLINE_INITIALIZED
-    global __PLOTLY_USE_CDN
-
-    __PLOTLY_USE_CDN = connected
 
     if connected:
         # Inject plotly.js into the output cell
@@ -69,14 +85,15 @@ def init_notebook_mode(connected=False):
             '<script>'
             'requirejs.config({'
             'paths: { '
+            # Note we omit the extension .js because require will include it.
             '\'plotly\': [\'https://cdn.plot.ly/plotly-latest.min\']},'
             '});'
             'if(!window.Plotly) {{'
             'require([\'plotly\'],'
             'function(plotly) {window.Plotly=plotly;});'
             '}}'
             '</script>'
-            )
+        )
     else:
         # Inject plotly.js into the output cell
         script_inject = (
