Repository: bokeh/bokeh

Issue:
Better docs for the Chord chart.
In order to make easier for the users the creation of Chord charts, the basic documentation has been enhanced as seen in  #4226.

This should let everyone to make chord charts from `pandas.Dataframe` as well as squared `numpy.array`.

An example can be found too in the docs as well as in the `examples` directory at the root of the repository.



Discussion:

Resolving patch:
diff --git a/bokeh/charts/builders/chord_builder.py b/bokeh/charts/builders/chord_builder.py
--- a/bokeh/charts/builders/chord_builder.py
+++ b/bokeh/charts/builders/chord_builder.py
@@ -238,13 +238,23 @@ def yield_renderers(self):
 
 
 @help(ChordBuilder)
-def Chord(data, source=None, target=None, value=None, square_matrix=False, label=None, **kws):
-    """ Create a chord chart using :class:`ChordBuilder <bokeh.charts.builders.chord_builder.ChordBuilder>`
+def Chord(data, source=None, target=None, value=None, square_matrix=False, label=None, xgrid=False, ygrid=False, **kw):
+    """
+    Create a chord chart using :class:`ChordBuilder <bokeh.charts.builders.chord_builder.ChordBuilder>`
     to render a chord graph from a variety of value forms.
-
     This chart displays the inter-relationships between data in a matrix.
 
-    The data can be generated by the chart interface. Given a source
+    The data can be generated by the chart interface. Given a :class:`DataFrame <pandas.DataFrame>`,
+    select two columns to be used as arcs with `source` and `target` attributes, passing by the name of those columns.
+    The :class:`Chord <bokeh.charts.builders.chord_builder.Chord>` chart will then deduce the
+    relationship between the arcs.
+
+    The value of the connections can be inferred automatically by counting `source` and `target`. If you prefer
+    you can assign a fixed value for all the connections with `value` simply passing by a number. A third option is to
+    pass a reference to a third column in the :class:`DataFrame <pandas.DataFrame>` with the values for the connections.
+
+    If you want to plot the relationships in a squared matrix, simply pass the matrix and set `square_matrix` attribute
+    to `True`.
 
     Reference: `Chord diagram on Wikipedia <https://en.wikipedia.org/wiki/Chord_diagram>`_
 
@@ -254,7 +264,7 @@ def Chord(data, source=None, target=None, value=None, square_matrix=False, label
         target (list(str) or str, optional): Data source to use as destination of a connection.
         value (list(num) or num, optional): The value the connection should have.
         square_matrix (bool, optional): If square matrix, avoid any calculations during the setup.
-        label (list(str or num) optional): The labels to be put in the areas.
+        label (list(str), optional): The labels to be put in the areas.
 
     Returns:
         :class:`Chart`: includes glyph renderers that generate the chord
@@ -264,31 +274,39 @@ def Chord(data, source=None, target=None, value=None, square_matrix=False, label
     .. bokeh-plot::
         :source-position: above
 
-            import pandas as pd
-            from bokeh.charts import output_file, Chord
-            from bokeh.io import show
-            from bokeh.sampledata.les_mis import data
+        import pandas as pd
+        from bokeh.charts import Chord
+        from bokeh.io import show, output_file
+        from bokeh.sampledata.les_mis import data
 
-            nodes = data['nodes']
-            links = data['links']
+        nodes = data['nodes']
+        links = data['links']
 
-            nodes_df = pd.DataFrame(nodes)
-            links_df = pd.DataFrame(links)
+        nodes_df = pd.DataFrame(nodes)
+        links_df = pd.DataFrame(links)
 
-            source_data = links_df.merge(nodes_df, how='left', left_on='source', right_index=True)
-            source_data = source_data.merge(nodes_df, how='left', left_on='target', right_index=True)
-            source_data = source_data[source_data["value"] > 5]
+        source_data = links_df.merge(nodes_df, how='left', left_on='source', right_index=True)
+        source_data = source_data.merge(nodes_df, how='left', left_on='target', right_index=True)
+        source_data = source_data[source_data["value"] > 5]  # Select those with 5 or more connections
 
-            chord_from_df = Chord(source_data, source="name_x", target="name_y", value="value")
-            output_file('chord_from_df.html', mode="inline")
-            show(chord_from_df)
+        chord_from_df = Chord(source_data, source="name_x", target="name_y", value="value")
+        output_file('chord_from_df.html')
+        show(chord_from_df)
 
     """
 
-    kws["origin"] = source
-    kws["destination"] = target
-    kws["value"] = value
-    kws["square_matrix"] = square_matrix
-    kws["label"] = label
+    kw["origin"] = source
+    kw["destination"] = target
+    kw["value"] = value
+    kw["square_matrix"] = square_matrix
+    kw["label"] = label
+    kw['xgrid'] = xgrid
+    kw['ygrid'] = ygrid
+
+    chart = create_and_build(ChordBuilder, data, **kw)
+
+    chart.left[0].visible = False
+    chart.below[0].visible = False
+    chart.outline_line_color = None
 
-    return create_and_build(ChordBuilder, data, **kws)
+    return chart


Test patch: