Repository: bokeh/bokeh

Issue:
Wrong variable names  in file_html() for Jinja2 template in documentation
Hi,
in the documentation,  file_html(..) is somehow wrong: it says "variables to be used in the Jinja2 template. If used, the following variable names will be overwritten: title, js_resources, css_resources, plot_script, plot_div". See: http://bokeh.pydata.org/en/0.10.0/docs/reference/resources_embedding.html

I think _js_resources_ must be _bokeh_css_ and _css_resources_ must be _bokeh_js_, according to https://github.com/bokeh/bokeh/blob/master/bokeh/embed.py. Otherwise it won't work for me.

The parameters js_resources=None, css_resources=None are not explained in detail, only named in the method's signature.



Discussion:

Resolving patch:
diff --git a/bokeh/embed.py b/bokeh/embed.py
--- a/bokeh/embed.py
+++ b/bokeh/embed.py
@@ -260,14 +260,19 @@ def file_html(plot_objects,
     Args:
         plot_objects (PlotObject or Document or list) : Bokeh object or objects to render
             typically a PlotObject or Document
-        resources (Resources) : a resource configuration for BokehJS assets
+        resources (Resources) : a resource configuration for Bokeh JS & CSS assets. Pass ``None`` if
+            using js_resources of css_resources manually.
         title (str) : a title for the HTML document ``<title>`` tags
+        js_resources (JSResources, optional): custom JS Resources (default: ``None``), if
+            resources is also provided, resources will override js_resources.
+        css_resources (CSSResources, optional): custom CSS Resources (default: ``None``), if
+            resources is also provided, resources will override css_resources.
         template (Template, optional) : HTML document template (default: FILE)
             A Jinja2 Template, see bokeh.templates.FILE for the required
             template parameters
         template_variables (dict, optional) : variables to be used in the Jinja2
             template. If used, the following variable names will be overwritten:
-            title, js_resources, css_resources, plot_script, plot_div
+            title, bokeh_js, bokeh_css, plot_script, plot_div
 
     Returns:
         UTF-8 encoded HTML
diff --git a/bokeh/resources.py b/bokeh/resources.py
--- a/bokeh/resources.py
+++ b/bokeh/resources.py
@@ -2,7 +2,7 @@
 how BokehJS code and CSS resources should be located, loaded, and embedded in
 Bokeh documents.
 
-Also provides some pre-configured Resources objects:
+Also provides some pre-configured Resources objects.
 
 Attributes:
     CDN : load minified BokehJS from CDN
@@ -27,6 +27,7 @@
 DEFAULT_SERVER_PORT = 5006
 DEFAULT_SERVER_HTTP_URL = "http://%s:%d/" % (DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT)
 
+
 def websocket_url_for_server_url(url):
     if url.startswith("http:"):
         reprotocoled = "ws" + url[4:]
@@ -39,6 +40,7 @@ def websocket_url_for_server_url(url):
     else:
         return reprotocoled + "/ws"
 
+
 def server_url_for_websocket_url(url):
     if url.startswith("ws:"):
         reprotocoled = "http" + url[2:]
@@ -54,9 +56,11 @@ def server_url_for_websocket_url(url):
 
 _DEV_PAT = re.compile(r"^(\d)+\.(\d)+\.(\d)+(dev|rc)")
 
+
 def _cdn_base_url():
     return "http://cdn.pydata.org"
 
+
 def _get_cdn_urls(components, version=None, minified=True):
     if version is None:
         if settings.docs_cdn():
@@ -94,6 +98,7 @@ def mk_url(comp, kind):
 
     return result
 
+
 def _get_server_urls(components, root_url, minified=True):
     _min = ".min" if minified else ""
 
@@ -105,6 +110,7 @@ def mk_url(comp, kind):
         'messages' : [],
     }
 
+
 class BaseResources(object):
     _default_root_dir = "."
     _default_root_url = DEFAULT_SERVER_HTTP_URL
@@ -232,7 +238,52 @@ def _use_component(self, component, use):
     def use_widgets(self, use):
         return self._use_component("bokeh-widgets", use)
 
+
 class JSResources(BaseResources):
+    ''' The Resources class encapsulates information relating to loading or embedding Bokeh Javascript.
+
+    Args:
+        mode (str) : how should Bokeh JS be included in output
+
+            See below for descriptions of available modes
+
+        version (str, optional) : what version of Bokeh JS to load
+
+            Only valid with the ``'cdn'`` mode
+
+        root_dir (str, optional) : root directory for loading Bokeh JS assets
+
+            Only valid with ``'relative'`` and ``'relative-dev'`` modes
+
+        minified (bool, optional) : whether JavaScript should be minified or not (default: True)
+
+        root_url (str, optional) : URL and port of Bokeh Server to load resources from
+
+            Only valid with ``'server'`` and ``'server-dev'`` modes
+
+    The following **mode** values are available for configuring a Resource object:
+
+    * ``'inline'`` configure to provide entire Bokeh JS and CSS inline
+    * ``'cdn'`` configure to load Bokeh JS and CSS from ``http://cdn.pydata.org``
+    * ``'server'`` configure to load from a Bokeh Server
+    * ``'server-dev'`` same as ``server`` but supports non-minified assets
+    * ``'relative'`` configure to load relative to the given directory
+    * ``'relative-dev'`` same as ``relative`` but supports non-minified assets
+    * ``'absolute'`` configure to load from the installed Bokeh library static directory
+    * ``'absolute-dev'`` same as ``absolute`` but supports non-minified assets
+
+    Once configured, a Resource object exposes the following public attributes:
+
+    Attributes:
+        logo_url : location of the BokehJS logo image
+        css_raw : any raw CSS that needs to be places inside ``<style>`` tags
+        css_files : URLS od any CSS files that need to be loaed by ``<link>`` tags
+        messages : any informational messages concering this configuration
+
+    These attributes are often useful as template parameters when embedding
+    Bokeh plots.
+
+    '''
 
     def _autoload_path(self, elementid):
         return self.root_url + "bokeh/autoload.js/%s" % elementid
@@ -250,7 +301,51 @@ def js_raw(self):
     def render_js(self):
         return JS_RESOURCES.render(js_raw=self.js_raw, js_files=self.js_files)
 
+
 class CSSResources(BaseResources):
+    ''' The CSSResources class encapsulates information relating to loading or embedding Bokeh client-side CSS.
+
+    Args:
+        mode (str) : how should Bokeh CSS be included in output
+
+            See below for descriptions of available modes
+
+        version (str, optional) : what version of Bokeh CSS to load
+
+            Only valid with the ``'cdn'`` mode
+
+        root_dir (str, optional) : root directory for loading BokehJS resources
+
+            Only valid with ``'relative'`` and ``'relative-dev'`` modes
+
+        minified (bool, optional) : whether CSS should be minified or not (default: True)
+
+        root_url (str, optional) : URL and port of Bokeh Server to load resources from
+
+            Only valid with ``'server'`` and ``'server-dev'`` modes
+
+    The following **mode** values are available for configuring a Resource object:
+
+    * ``'inline'`` configure to provide entire BokehJS code and CSS inline
+    * ``'cdn'`` configure to load Bokeh CSS from ``http://cdn.pydata.org``
+    * ``'server'`` configure to load from a Bokeh Server
+    * ``'server-dev'`` same as ``server`` but supports non-minified CSS
+    * ``'relative'`` configure to load relative to the given directory
+    * ``'relative-dev'`` same as ``relative`` but supports non-minified CSS
+    * ``'absolute'`` configure to load from the installed Bokeh library static directory
+    * ``'absolute-dev'`` same as ``absolute`` but supports non-minified CSS
+
+    Once configured, a Resource object exposes the following public attributes:
+
+    Attributes:
+        logo_url : location of the BokehJS logo image
+        css_raw : any raw CSS that needs to be places inside ``<style>`` tags
+        css_files : URLS od any CSS files that need to be loaed by ``<link>`` tags
+        messages : any informational messages concering this configuration
+
+    These attributes are often useful as template parameters when embedding Bokeh plots.
+
+    '''
 
     @property
     def css_files(self):
@@ -265,20 +360,21 @@ def css_raw(self):
     def render_css(self):
         return CSS_RESOURCES.render(css_raw=self.css_raw, css_files=self.css_files)
 
+
 class Resources(JSResources, CSSResources):
     ''' The Resources class encapsulates information relating to loading or
-    embedding BokehJS code and CSS.
+    embedding Bokeh Javascript and CSS.
 
     Args:
-        mode (str) : how should BokehJS be included in output
+        mode (str) : how should Bokeh JS and CSS be included in output
 
             See below for descriptions of available modes
 
-        version (str, optional) : what version of BokejJS to load
+        version (str, optional) : what version of Bokeh JS and CSS to load
 
             Only valid with the ``'cdn'`` mode
 
-        root_dir (str, optional) : root directory for loading BokehJS resources
+        root_dir (str, optional) : root directory for loading Bokeh JS and CSS assets
 
             Only valid with ``'relative'`` and ``'relative-dev'`` modes
 
@@ -290,14 +386,14 @@ class Resources(JSResources, CSSResources):
 
     The following **mode** values are available for configuring a Resource object:
 
-    * ``'inline'`` configure to provide entire BokehJS code and CSS inline
-    * ``'cdn'`` configure to load BokehJS code and CS from ``http://cdn.pydata.org``
+    * ``'inline'`` configure to provide entire Bokeh JS and CSS inline
+    * ``'cdn'`` configure to load Bokeh JS and CSS from ``http://cdn.pydata.org``
     * ``'server'`` configure to load from a Bokeh Server
-    * ``'server-dev'`` same as ``server`` but supports non-minified JS
+    * ``'server-dev'`` same as ``server`` but supports non-minified assets
     * ``'relative'`` configure to load relative to the given directory
-    * ``'relative-dev'`` same as ``relative`` but supports non-minified JS
+    * ``'relative-dev'`` same as ``relative`` but supports non-minified assets
     * ``'absolute'`` configure to load from the installed Bokeh library static directory
-    * ``'absolute-dev'`` same as ``absolute`` but supports non-minified JS
+    * ``'absolute-dev'`` same as ``absolute`` but supports non-minified assets
 
     Once configured, a Resource object exposes the following public attributes:
 


Test patch: