12066 sphinx extention for sampledata (#12086)

* [12066] initial push * [12066] initial push * [12066] initial push * [12066] initial push * [12066] initial push * [12066] changes for flake8 * [12066] fix example_sampledata.rst * [12066] add "bokeh-example-sampledata" to sampledata * remove whitespace * remove trailing whitespace * Delete sampledata.csv * [12066] add parsing of samples to plot-bokeh * [12066] make flake8 happy * isort * rename Directiv to BokehSampledataXrefDirective * remove f-string * reduce diff
bokeh · Apr 27, 2022 · f7989e1 · f7989e1
1 parent 9e2399a
commit f7989e1
Show file tree

Hide file tree

Showing 37 changed files with 227 additions and 8 deletions.
diff --git a/bokeh/sampledata/airport_routes.py b/bokeh/sampledata/airport_routes.py
@@ -20,6 +20,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.airport_routes.routes`
 
+.. bokeh-sampledata-xref:: airport_routes
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/airports.py b/bokeh/sampledata/airports.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.airports.data`
 
+.. bokeh-sampledata-xref:: airports
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/anscombe.py b/bokeh/sampledata/anscombe.py
@@ -16,8 +16,9 @@
 
 :bokeh-dataframe:`bokeh.sampledata.anscombe.data`
 
-.. _Anscombe's Quartet: https://en.wikipedia.org/wiki/Anscombe%27s_quartet
+.. bokeh-sampledata-xref:: anscombe
 
+.. _Anscombe's Quartet: https://en.wikipedia.org/wiki/Anscombe%27s_quartet
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/antibiotics.py b/bokeh/sampledata/antibiotics.py
@@ -17,8 +17,9 @@
 
 :bokeh-dataframe:`bokeh.sampledata.antibiotics.data`
 
-.. _Will Burtin's historical data: https://medium.com/@harshdev_41068/burtins-legendary-data-on-antibiotics-9b32ecd5943f
+.. bokeh-sampledata-xref:: antibiotics
 
+.. _Will Burtin's historical data: https://medium.com/@harshdev_41068/burtins-legendary-data-on-antibiotics-9b32ecd5943f
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/autompg.py b/bokeh/sampledata/autompg.py
@@ -21,6 +21,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.autompg.autompg_clean`
 
+.. bokeh-sampledata-xref:: autompg
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/autompg2.py b/bokeh/sampledata/autompg2.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.autompg2.autompg2`
 
+.. bokeh-sampledata-xref:: autompg2
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/browsers.py b/bokeh/sampledata/browsers.py
@@ -21,6 +21,7 @@
 The module also contains a dictionary ``icons`` with base64-encoded PNGs of the
 logos for Chrome, Firefox, Safari, Opera, and IE.
 
+.. bokeh-sampledata-xref:: browsers
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/commits.py b/bokeh/sampledata/commits.py
@@ -14,6 +14,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.commits.data`
 
+.. bokeh-sampledata-xref:: commits
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/daylight.py b/bokeh/sampledata/daylight.py
@@ -16,8 +16,9 @@
 
 :bokeh-dataframe:`bokeh.sampledata.daylight.daylight_warsaw_2013`
 
-.. _this FAQ: https://www.sunrisesunset.com/faqs.asp#other_usage
+.. bokeh-sampledata-xref:: daylight
 
+.. _this FAQ: https://www.sunrisesunset.com/faqs.asp#other_usage
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/degrees.py b/bokeh/sampledata/degrees.py
@@ -18,6 +18,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.degrees.data`
 
+.. bokeh-sampledata-xref:: degrees
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/gapminder.py b/bokeh/sampledata/gapminder.py
@@ -29,6 +29,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.gapminder.regions`
 
+.. bokeh-sampledata-xref:: gapminder
 '''
 
 

diff --git a/bokeh/sampledata/glucose.py b/bokeh/sampledata/glucose.py
@@ -12,6 +12,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.glucose.data`
 
+.. bokeh-sampledata-xref:: glucose
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/haar_cascade.py b/bokeh/sampledata/haar_cascade.py
@@ -14,8 +14,9 @@
 attribute to obtain the path to a Haar cascade file for frontal face
 recognition that can be used by OpenCV.
 
-.. _OpenCV: https://opencv.org
+.. bokeh-sampledata-xref:: haar_cascade
 
+.. _OpenCV: https://opencv.org
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/iris.py b/bokeh/sampledata/iris.py
@@ -20,6 +20,8 @@
 
 :bokeh-dataframe:`bokeh.sampledata.iris.flowers`
 
+.. bokeh-sampledata-xref:: iris
+
 .. _Fisher's Iris dataset: https://en.wikipedia.org/wiki/Iris_flower_data_se
 .. _alternatives to Iris: https://www.meganstodel.com/posts/no-to-iris/
 

diff --git a/bokeh/sampledata/les_mis.py b/bokeh/sampledata/les_mis.py
@@ -29,6 +29,7 @@
         ]
     }
 
+.. bokeh-sampledata-xref:: les_mis
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/movies_data.py b/bokeh/sampledata/movies_data.py
@@ -13,8 +13,9 @@
 This modules has an attribute ``movie_path``. This attribute contains the path
 to a SQLite database with the data.
 
-.. _Open Movie Database: http://www.omdbapi.com
+.. bokeh-sampledata-xref:: movies_data
 
+.. _Open Movie Database: http://www.omdbapi.com
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/mtb.py b/bokeh/sampledata/mtb.py
@@ -14,6 +14,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.mtb.obiszow_mtb_xcm`
 
+.. bokeh-sampledata-xref:: mtb
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/olympics2014.py b/bokeh/sampledata/olympics2014.py
@@ -21,6 +21,7 @@
         'name': 'Germany'
     }
 
+.. bokeh-sampledata-xref:: olympics2014
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/penguins.py b/bokeh/sampledata/penguins.py
@@ -16,8 +16,9 @@
 
 :bokeh-dataframe:`bokeh.sampledata.penguins.data`
 
-.. _Palmer Archipelago (Antarctica) penguin dataset: https://github.com/allisonhorst/palmerpenguins
+.. bokeh-sampledata-xref:: penguins
 
+.. _Palmer Archipelago (Antarctica) penguin dataset: https://github.com/allisonhorst/palmerpenguins
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/perceptions.py b/bokeh/sampledata/perceptions.py
@@ -20,6 +20,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.perceptions.numberly`
 
+.. bokeh-sampledata-xref:: perceptions
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/periodic_table.py b/bokeh/sampledata/periodic_table.py
@@ -14,6 +14,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.periodic_table.elements`
 
+.. bokeh-sampledata-xref:: periodic_table
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/population.py b/bokeh/sampledata/population.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.population.data`
 
+.. bokeh-sampledata-xref:: population
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/sample_geojson.py b/bokeh/sampledata/sample_geojson.py
@@ -12,6 +12,7 @@
 
 A snapshot of data available from NHS Choices on November 14th, 2015.
 
+.. bokeh-sampledata-xref:: sample_geojson
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/sea_surface_temperature.py b/bokeh/sampledata/sea_surface_temperature.py
@@ -16,8 +16,9 @@
 
 :bokeh-dataframe:`bokeh.sampledata.sea_surface_temperature.sea_surface_temperature`
 
-.. _this table: http://www.neracoos.org/erddap/info/B01_sbe37_all/index.html
+.. bokeh-sampledata-xref:: sea_surface_temperature
 
+.. _this table: http://www.neracoos.org/erddap/info/B01_sbe37_all/index.html
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/sprint.py b/bokeh/sampledata/sprint.py
@@ -14,6 +14,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.sprint.sprint`
 
+.. bokeh-sampledata-xref:: sprint
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/stocks.py b/bokeh/sampledata/stocks.py
@@ -22,6 +22,7 @@
     AAPL['volume']     # list of int
     AAPL['adj_close']  # list of float
 
+.. bokeh-sampledata-xref:: stocks
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/unemployment.py b/bokeh/sampledata/unemployment.py
@@ -23,6 +23,7 @@
         ...
     }
 
+.. bokeh-sampledata-xref:: unemployment
 '''
 #-----------------------------------------------------------------------------
 # Boilerplate

diff --git a/bokeh/sampledata/unemployment1948.py b/bokeh/sampledata/unemployment1948.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.unemployment1948.data`
 
+.. bokeh-sampledata-xref:: unemployment1948
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/us_cities.py b/bokeh/sampledata/us_cities.py
@@ -17,6 +17,7 @@
     data['lat']  # list of float
     data['lon']  # list of float
 
+.. bokeh-sampledata-xref:: us_cities
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/us_counties.py b/bokeh/sampledata/us_counties.py
@@ -26,6 +26,7 @@
 Entries for ``'name'`` can have duplicates for certain states (e.g. Virginia).
 The combination of ``'detailed name'`` and ``'state'`` will always be unique.
 
+.. bokeh-sampledata-xref:: us_counties
 '''
 #-----------------------------------------------------------------------------
 # Boilerplate

diff --git a/bokeh/sampledata/us_holidays.py b/bokeh/sampledata/us_holidays.py
@@ -23,8 +23,9 @@
         (datetime.date(2020, 12, 25), 'Christmas Day (US-OPM)')
     ]
 
-.. _icalendar: https://pypi.org/project/icalendar/
+.. bokeh-sampledata-xref:: us_holidays
 
+.. _icalendar: https://pypi.org/project/icalendar/
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/us_marriages_divorces.py b/bokeh/sampledata/us_marriages_divorces.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.us_marriages_divorces.data`
 
+.. bokeh-sampledata-xref:: us_marriages_divorces
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/us_states.py b/bokeh/sampledata/us_states.py
@@ -22,6 +22,7 @@
         'lons': [-124.03622, ..., -124.15935]
     }
 
+.. bokeh-sampledata-xref:: us_states
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sampledata/world_cities.py b/bokeh/sampledata/world_cities.py
@@ -16,6 +16,7 @@
 
 :bokeh-dataframe:`bokeh.sampledata.world_cities.data`
 
+.. bokeh-sampledata-xref:: world_cities
 '''
 
 #-----------------------------------------------------------------------------

diff --git a/bokeh/sphinxext/bokeh_plot.py b/bokeh/sphinxext/bokeh_plot.py
@@ -146,6 +146,8 @@ def visit_html(visitor, node):
 
     html = visit_html.__func__, None
 
+class sampledata_node(nodes.General, nodes.Element):
+    pass
 
 class BokehPlotDirective(BokehDirective):
 
@@ -175,6 +177,8 @@ def run(self):
         target_id = f"{dashed_docname}.{basename(js_path)}"
         target = [nodes.target("", "", ids=[target_id])]
 
+        self.process_sampledata(target, source)
+
         process_docstring = self.options.get("process-docstring", False)
         intro = self.parse(docstring, '<bokeh-content>') if docstring and process_docstring else []
 
@@ -237,6 +241,26 @@ def process_source(self, source, path, js_filename):
 
         return (script_tag, js_path, source, docstring, height_hint)
 
+    def process_sampledata(self, targetnode, source):
+
+        if not hasattr(self.env, 'all_sampledata_xrefs'):
+            self.env.all_sampledata_xrefs = []
+
+        regex = "(:|bokeh\.)sampledata(:|\.| import )\s*(\w+(\,\s*\w+)*)"
+        matches = re.findall(regex, source)
+        if matches:
+            keywords = set()
+            for m in matches:
+                keywords.update(m[2].replace(" ","").split(','))
+            for keyword in keywords:
+                xref_node = sampledata_node('')
+                self.state.nested_parse(self.content, self.content_offset, xref_node)
+
+                self.env.all_sampledata_xrefs.append({
+                    'docname': self.env.docname,
+                    'target': targetnode,
+                    'keyword': keyword
+                })
 # -----------------------------------------------------------------------------
 # Dev API
 # -----------------------------------------------------------------------------
@@ -267,6 +291,7 @@ def env_merge_info(app, env, docnames, other):
 
 def setup(app):
     """ Required Sphinx extension setup function. """
+    app.add_node(sampledata_node)
     app.add_directive("bokeh-plot", BokehPlotDirective)
     app.add_node(autoload_script, html=autoload_script.html)
     app.add_config_value("bokeh_missing_google_api_key_ok", True, "html")