build: Add snapshot generator

.dockerignore

@@ -51,3 +51,7 @@ playwright/.cache/
 
 # Ignore docs
 **/*.md
+**/docs/
+
+# Ignore test cache
+**/.tox/

.github/workflows/e2e.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run tests
-        run: './tools/run_docker.sh e2e-tests'
+        run: './tools/run_docker.sh ./tests/docker-compose.yml e2e-tests'
 
       - name: Upload Playwright report
         uses: actions/upload-artifact@v4

.gitignore

@@ -45,4 +45,8 @@ hs_err_pid*
 replay_pid*
 
 plugins-venv/
-plugins-dev-venv/
+plugins-dev-venv/
+
+# Docs snapshots
+extract-results/
+snapshot-results/

Dockerfile

@@ -20,7 +20,7 @@ COPY package.json package-lock.json requirements.txt ./
 # cd first so the cp doesn't include /tmp/deephaven-plugins in the paths
 RUN cd /tmp/deephaven-plugins && cp --parents ./*/src/js/package.json /work/ && cp --parents ./*/setup.* /work/
 
-FROM base as build
+FROM base AS build
 WORKDIR /work/
 COPY --from=copy-plugins /work/ .
 
@@ -59,3 +59,5 @@ COPY --link docker/data /data
 
 # Set the environment variable to enable the JS plugins embedded in Python
 ENV DEEPHAVEN_ENABLE_PY_JS=true
+
+HEALTHCHECK --interval=3s --retries=3 --timeout=11s CMD /opt/grpc_health_probe/grpc_health_probe -addr=localhost:10000 -connect-timeout=10s || exit 1

README.md

@@ -289,6 +289,14 @@ python tools/plugin_builder.py --docs --install ui
 
 After the first time install, you can drop the `--install` flag and just run the script with `--docs` unless you have plugin changes.
 
+You can also re-generate the snapshots for the docs by passing the `--snapshots` flag. This should be done when new code blocks are added to the docs.
+
+This example will build the docs for the `ui` plugin and re-generate the snapshots:
+
+```shell
+python tools/plugin_builder.py --docs --snapshots ui
+```
+
 To run the server, pass the `--server` flag.  
 First install `deephaven-server` if it is not already installed (if setup with `--configure=full` this is already done):
 
@@ -357,6 +365,10 @@ python tools/plugin_builder.py -d ui plotly-express
 BUILT=true npm run docs
 ```
 
+### Snapshotting docs with npm
+
+You can also use `npm` to snapshot the docs instead of using the `--snapshots` flag in `plugin_builder.py`. Just run `npm run update-doc-snapshots` from the root directory of this repo. This will run the snapshotting script and update the snapshots in the `docs` directory.
+
 ## Release Management
 
 In order to manage changelogs, version bumps and github releases, we use [cocogitto](https://github.com/cocogitto/cocogitto), or `cog` for short. Follow the [Installation instructions](https://github.com/cocogitto/cocogitto?tab=readme-ov-file#installation) to install `cog`. For Linux and Windows, we recommend using [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) to install. For MacOS, we recommend using [brew](https://brew.sh/).

docker-compose.docs-snapshots.yml

@@ -0,0 +1,63 @@
+services:
+  # Test server that has all the plugins loaded. Test sets are run against this server.
+  deephaven-plugins-docs-test-server:
+    container_name: deephaven-plugins
+    build:
+      dockerfile: ./Dockerfile
+      pull: true # We need to always pull the latest server image used in the Dockerfile
+    ports:
+      - '${DEEPHAVEN_SNAPSHOT_PORT:-10090}:10000'
+    environment:
+      - START_OPTS=-Xmx4g -DAuthHandlers=io.deephaven.auth.AnonymousAuthenticationHandler -Ddeephaven.console.type=python
+
+  # Extract the code blocks from the docs in the plugins directories and output them ssto a results directory.
+  deephaven-plugins-docs-extractor:
+    image: ghcr.io/deephaven/salmon-extractor
+    pull_policy: always
+    container_name: deephaven-plugins-docs-extractor
+    command:
+      [
+        'sh',
+        '-c',
+        'node extract.cjs --directory /extract/plotly-express --output /results/plotly-express; node extract.cjs --directory /extract/ui --output /results/ui',
+      ]
+    volumes:
+      - ./plugins/ui/docs:/extract/ui
+      - ./plugins/plotly-express/docs:/extract/plotly-express
+      # exclude doc build directories by overriding with empty volumes
+      # We could extract from the build directories, but we need to output the snapshots to the build directory itself for Salmon to pick up...
+      - /extract/plotly-express/build/
+      - /extract/ui/build/
+      - ./docker/build/test-sets:/results # Output to a temporary build directory
+
+  # Read the test sets from the results directory and run them against the test server, taking a snapshot of the results.
+  deephaven-plugins-docs-snapshotter:
+    image: ghcr.io/deephaven/salmon-snapshotter
+    pull_policy: always
+    depends_on:
+      deephaven-plugins-docs-test-server:
+        condition: service_healthy
+      deephaven-plugins-docs-extractor:
+        condition: service_completed_successfully
+    environment:
+      HOST_URL: 'http://deephaven-plugins-docs-test-server:10000'
+    command:
+      [
+        'sh',
+        '-c',
+        'node snapshot.cjs --directory /test-sets/plotly-express --output /results/plotly-express; node snapshot.cjs --directory /test-sets/ui --output /results/ui',
+      ]
+    volumes:
+      - ./docker/build/test-sets:/test-sets
+      # Map all the results back to the snapshots directory for those docs
+      - ./plugins/ui/docs/snapshots:/results/ui
+      - ./plugins/plotly-express/docs/snapshots:/results/plotly-express
+
+  # Validate MDX and the snapshots that were written are valid
+  deephaven-plugins-docs-validator:
+    image: ghcr.io/deephaven/salmon-validator
+    pull_policy: always
+    volumes:
+      - ./plugins/ui/docs/build/markdown:/validate/ui
+      - ./plugins/plotly-express/docs/build/markdown:/validate/plotly-express
+      - ./docker/build/validator-results:/results

docker/.gitignore

@@ -0,0 +1 @@
+build/

package.json

@@ -22,10 +22,12 @@
     "test:ci:lint": "jest --config jest.config.lint.cjs --ci --cacheDirectory $PWD/.jest-cache",
     "e2e": "playwright test",
     "e2e:ui": "playwright test --ui",
-    "e2e:docker": "DEEPHAVEN_PORT=10001 ./tools/run_docker.sh e2e-tests",
-    "e2e:update-snapshots": "./tools/run_docker.sh update-snapshots",
+    "e2e:docker": "DEEPHAVEN_PORT=10001 ./tools/run_docker.sh ./tests/docker-compose.yml e2e-tests",
+    "e2e:update-snapshots": "./tools/run_docker.sh ./tests/docker-compose.yml update-snapshots",
     "update-dh-packages": "lerna run --concurrency 1 update-dh-packages",
-    "update-dh-packages:ui": "npm run update-dh-packages -- --scope=@deephaven/js-plugin-ui --"
+    "update-dh-packages:ui": "npm run update-dh-packages -- --scope=@deephaven/js-plugin-ui --",
+    "update-doc-snapshots": "./tools/run_docker.sh ./docker-compose.docs-snapshots.yml deephaven-plugins-docs-snapshotter",
+    "validate-doc-snapshots": "./tools/run_docker.sh ./docker-compose.docs-snapshots.yml deephaven-plugins-docs-validator"
   },
   "devDependencies": {
     "@deephaven/babel-preset": "^0.72.0",

plugins/plotly-express/conf.py

@@ -27,6 +27,7 @@
     "sphinx_markdown_builder",
     "sphinx_autodoc_typehints",
     "deephaven_autodoc",
+    "deephaven_code_block",
 ]
 
 source_suffix = [".rst", ".md"]  # Can use either rst or markdown files as input
@@ -41,6 +42,7 @@
 always_use_bars_union = True
 
 myst_all_links_external = True
+myst_fence_as_directive = ("python", "groovy")
 
 from deephaven_server import Server
 

plugins/plotly-express/docs/area.md

@@ -26,8 +26,6 @@ usa_population = gapminder.where("Country == `United States`")
 area_plot = dx.area(usa_population, x="Year", y="Pop")
 ```
 
-![Area Plot Basic Example](./_assets/area_plot.png)
-
 ### Area by group
 
 Area plots are unique in that the y-axis demonstrates each groups' total contribution to the whole. Pass the name of the grouping column(s) to the `by` argument.
@@ -47,7 +45,7 @@ area_plot_group = dx.area(large_countries_population, x="Year", y="Pop", by="Cou
 
 Area plots take a calendar argument. Dates and times are excluded from axes so that they conform to the calendar.
 
-```python
+```python order=area_plot_default,area_plot_cal_name,area_plot_cal_y,area_plot_cal,dog_prices,stocks
 import deephaven.plot.express as dx
 from deephaven.calendar import calendar, set_calendar
 

plugins/plotly-express/docs/bar.md

@@ -23,8 +23,6 @@ tips = dx.data.tips()
 bar_plot = dx.bar(tips, x="Day", y="TotalBill")
 ```
 
-![Bar Plot Basic Example](./_assets/bar_plot.png)
-
 Change the x-axis ordering by sorting the dataset by the categorical variable.
 
 ```python order=ordered_bar_plot,tips
@@ -56,7 +54,7 @@ bar_plot_sex = dx.bar(sorted_tips, x="Day", y="TotalBill", by="Sex")
 
 Visualize the frequency of categories in a column by passing to either the `x` or `y` argument.
 
-```python
+```python order=bar_plot_vertical,bar_plot_horizontal,tips
 import deephaven.plot.express as dx
 
 tips = dx.data.tips()

plugins/plotly-express/docs/box.md

@@ -25,8 +25,6 @@ box_plot_x = dx.box(tips, x="TotalBill")
 box_plot_y = dx.box(tips, y="TotalBill")
 ```
 
-![Box Plot Basic Example](./_assets/box_plot.png)
-
 ### Distributions for multiple groups
 
 Box plots are useful for comparing the distributions of two or more groups of data. Pass the name of the grouping column(s) to the `by` argument.

plugins/plotly-express/docs/candlestick.md

@@ -46,13 +46,11 @@ candlestick_plot = dx.candlestick(
 )
 ```
 
-![Candlestick Plot Basic Example](./_assets/candlestick_plot.png)
-
 ### Calendar
 
 Candlestick plots take a calendar argument. Dates and times are excluded from axes so that they conform to the calendar.
 
-```python
+```python order=candlestick_plot_default,candlestick_plot_cal_name,candlestick_plot_cal,dog_prices,stocks_1min_dog,stocks
 import deephaven.plot.express as dx
 import deephaven.agg as agg
 from deephaven.calendar import calendar, set_calendar

plugins/plotly-express/docs/density_heatmap.md

@@ -23,13 +23,11 @@ iris = dx.data.iris()
 heatmap = dx.density_heatmap(iris, x="PetalLength", y="PetalWidth")
 ```
 
-![Heatmap Basic Example](./_assets/heatmap.png)
-
 ### A density heatmap with a custom color scale
 
 Custom color scales can be provided to the `color_continuous_scale` argument, and their range can be defined with the `range_color` argument.
 
-```py order=heatmap_colorscale,iris
+```python order=heatmap_colorscale,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
@@ -46,7 +44,7 @@ heatmap_colorscale = dx.density_heatmap(iris,
 
 The number of bins on each axis can be set using the `nbinsx` and `nbinsy` arguments. The number of bins significantly impacts the visualization by changing the granularity of the grid.
 
-```py order=heatmap_bins,iris
+```python order=heatmap_bins,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
@@ -66,7 +64,7 @@ heatmap_bins = dx.density_heatmap(
 
 Use an additional continuous variable to color the heatmap. Many statistical aggregations can be computed on this column by providing the `histfunc` argument. Possible values for the `histfunc` are `"abs_sum"`, `"avg"`, `"count"`, `"count_distinct"`, `"max"`, `"median"`, `"min"`, `"std"`, `"sum"`, and `"var"`.
 
-```py order=heatmap_aggregation,iris
+```python order=heatmap_aggregation,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 

plugins/plotly-express/docs/funnel-area.md

@@ -26,8 +26,6 @@ marketing = dx.data.marketing()
 funnel_area_plot = dx.funnel_area(marketing, names="Stage", values="Count")
 ```
 
-![Funnel Area Basic Example](./_assets/funnel_area.png)
-
 ## API Reference
 
 ```{eval-rst}

plugins/plotly-express/docs/funnel.md

@@ -26,8 +26,6 @@ marketing = dx.data.marketing()
 funnel_plot = dx.funnel(marketing, x="Count", y="Stage")
 ```
 
-![Funnel Plot Basic Example](./_assets/funnel_plot.png)
-
 ## API Reference
 
 ```{eval-rst}

plugins/plotly-express/docs/histogram.md

@@ -28,8 +28,6 @@ hist_plot_x = dx.histogram(setosa, x="SepalLength")
 hist_plot_y = dx.histogram(setosa, y="SepalLength")
 ```
 
-![Histogram Plot Basic Example](./_assets/histogram_plot.png)
-
 Modify the bin size by setting `nbins` equal to the number of desired bins.
 
 ```python order=hist_20_bins,hist_3_bins,hist_8_bins,virginica,iris
@@ -40,13 +38,13 @@ iris = dx.data.iris()
 virginica = iris.where("Species == `virginica`")
 
 # too many bins will produce jagged, disconnected histograms
-hist_20_bins = dx.histogram(setosa, x="SepalLength", nbins=20)
+hist_20_bins = dx.histogram(virginica, x="SepalLength", nbins=20)
 
 # too few bins will mask distributional information
-hist_3_bins = dx.histogram(setosa, x="SepalLength", nbins=3)
+hist_3_bins = dx.histogram(virginica, x="SepalLength", nbins=3)
 
 # play with the `nbins` parameter to get a good visualization
-hist_8_bins = dx.histogram(setosa, x="SepalLength", nbins=8)
+hist_8_bins = dx.histogram(virginica, x="SepalLength", nbins=8)
 ```
 
 ### Bin and aggregate on different columns

plugins/plotly-express/docs/icicle.md

@@ -31,27 +31,26 @@ gapminder_recent = (
 
 icicle_plot = dx.icicle(gapminder_recent, names="Continent", values="Pop", parents="World")
 ```
+
 ### An icicle plot with `path`
 
 Instead of manually aggregating and passing in `names` and `parents`, use the `path` argument to specify the hierarchy of the data. The first column is the root category, and the last column is the leaf category. The values are automatically summed up.
 
-```python order=treemap_path_plot,gapminder
+```python order=icicle_path_plot,gapminder
 import deephaven.plot.express as dx
 
 gapminder = dx.data.gapminder().update_view("World = `World`")
 
 icicle_path_plot = dx.icicle(gapminder, path=["World", "Continent", "Country"], values="Pop")
 ```
 
-![Icicle Plot Basic Example](./_assets/icicle_plot.png)
-
 # A nested icicle plot with branch values
 
 By default, the `branchvalues` argument is set to `"remainder"`.
 Keep the default if the values column should be added to the sum of its children to get the value for a node.
 If the values column is equal to the sum of its children, set `branchvalues` to `"total"`.
 
-```python
+```python order=icicle_nested,merged_gapminder,world,continents,countries
 import deephaven.plot.express as dx
 from deephaven import merge
 

plugins/plotly-express/docs/indicator.md

@@ -14,7 +14,7 @@ An indicator plot is a type of plot that highlights a collection of numeric valu
 
 Visualize a single numeric value by passing the column name to the `value` argument. The table should contain only one row.
 
-```python
+```python order=indicator_plot,dog_avg,my_table
 import deephaven.plot.express as dx
 from deephaven import agg as agg
 
@@ -26,8 +26,6 @@ dog_avg = my_table.where("Sym = `DOG`").agg_by([agg.avg(cols="Price")])
 indicator_plot = dx.indicator(dog_avg, value="Price")
 ```
 
-![Indicator Plot Basic Example](./_assets/indicator_plot.png)
-
 ### A delta indicator plot
 
 Visualize a single numeric value with a delta to a reference value by passing the reference column name to the `reference` argument.
@@ -134,7 +132,7 @@ The default format is set within the Settings panel. If only `value` is specifie
 If `reference` is specified, the default format is the `Integer` format if they are both integers. Otherwise, the default format is the `Decimal` format.  
 If a prefix or suffix is passed within the format string, it will be overridden by the `prefix` and `suffix` arguments.
 
-```python
+```python order=indicator_plot_prefix,indicator_plot,dog_avg,my_table
 import deephaven.plot.express as dx
 from deephaven import agg as agg
 
@@ -243,7 +241,7 @@ indicator_plot = dx.indicator(sym_avg, value="Price", by="Sym", cols=2)
 Change the color of the delta value based on whether it is increasing or decreasing by passing `increasing_color_sequence` and `decreasing_color_sequence`.
 These colors are applied sequentially to the indicators and looped if there are more indicators than colors.
 
-```python
+```python order=indicator_plot,sym_agg,my_table
 import deephaven.plot.express as dx
 from deephaven import agg as agg
 
@@ -268,7 +266,7 @@ indicator_plot = dx.indicator(
 Change the color of the gauge based on the value by passing `gauge_color_sequence`.
 These colors are applied sequentially to the indicators and looped if there are more indicators than colors.
 
-```python
+```python order=indicator_plot,sym_agg,my_table
 import deephaven.plot.express as dx
 from deephaven import agg as agg
 
@@ -287,7 +285,7 @@ indicator_plot = dx.indicator(
 Create groups of styled indicators by passing the grouping categorical column name to the `by` argument.
 `increasing_color_map` and `decreasing_color_map` can be used to style the indicators based on the group.
 
-```python
+```python order=indicator_plot,sym_agg,my_table
 import deephaven.plot.express as dx
 from deephaven import agg as agg
 

plugins/plotly-express/docs/layer-plots.md

@@ -37,8 +37,6 @@ financial_plot = dx.layer(
 )
 ```
 
-![Layer Plot Basic Example](./_assets/layer_plot.png)
-
 ## API Reference
 
 ```{eval-rst}