From 0a85e634d84fd086a0bcca369f502744f38b5a62 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Wed, 30 Apr 2025 11:32:47 +0100 Subject: [PATCH 1/3] Update documentation --- README.md | 85 ++++++++++++++++++++++++++++++++++++----------- recipes/README.md | 9 +++-- 2 files changed, 72 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c356bd7..edbb752 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,13 @@ # BokehJS Examples -Examples of integrating bokehjs with other libraries or tooling (e.g. webpack). +## Introduction -Initially contains TypeScripts examples, with others to follow later. +Examples using BokehJS as a standalone library without Python. -Cannot be built using a release NPM package of BokehJS and changes are required which will not be -released until BokehJS 4.0. In the meantime simple examples work using a particular Bokeh branch -which can be checked out and built in a temporary directory and the resultant NPM package copied -across to the root directory of this repository as follows. Note you will need `git` and `node` -installed. - -```bash -cd -git clone -b ianthomas23/13732_maybe_initialize --single-branch --depth 1 https://github.com/bokeh/bokeh.git -cd bokeh/bokehjs -node make build -npm pack -``` - -This will produce the file `bokeh-bokehjs-3.8.0-dev.1.tgz` which should be copied to the root -directory of the bokehjs-examples repository. +Currently contains examples of integrating BokehJS with TypeScript frameworks and build tools, +other possibilities to follow later. ---- +Here is an example of TypeScript code to produce a BokehJS plot: ```ts import * as Bokeh from "@bokeh/bokehjs"; @@ -46,4 +32,65 @@ function create_bokehjs_plot(): Bokeh.Plotting.Figure { Bokeh.Plotting.show(create_bokehjs_plot(), "#target"); ``` +and an image of the generated plot: + Example plot + + +## Contents + +### Examples + +The examples are located in the top-level `typescript` directory. The following combinations of +frameworks and build tools are included: + +Directory | Framework | Build tool +--- | --- | --- +angular_ng | [Angular](https://angular.dev/) | [ng](https://angular.dev/cli/build) +react_vite | [React](https://react.dev/) | [Vite](https://vite.dev/) +vanilla_rspack | None | [Rspack](https://rspack.dev/) +vanilla_vite | None | [Vite](https://vite.dev/) +vanilla_webpack | None | [Webpack](https://webpack.js.org/) +vue_vite | [Vue](https://vuejs.org/) | [Vite](https://vite.dev/) + +Each directory contains a `README.md` that describes the steps to follow to create a simple BokehJS +example using that combination of framework and build tool. There is also a subdirectory called +`created` that contains the files generated by following the steps in the `README.md`. +The easiest way to try out an example is to clone this repository, `cd` to the appropriate `created` +directory and build the example using `npm` commands from the `package.json` in the usual manner. + +### Recipes + +Each example is created from a recipe located in the `recipes` directory. Each recipe is a +TypeScript class that can be used to generate both a human-readable `README.md` file and a `bash` +script that can be used to automatically create the example. See `recipes/README.md` for more +information. + +### Testing + +All recipes are automatically recreated and tested once a week and whenever a PR is submitted to +this repository. The code for this is contained in the `ci` directory. The `bash` scripts to create +examples are in the `ci/typescript` directory; these can be individually run to create and build a +single example. The `ci/tests` directory contains the [Playwright](https://playwright.dev/) test +code and comparison images used in CI. For further details see the scripts in the `ci` directory +and the github action workflows in `.github/workflows/test.yml`. + +## Limitations + +Currently these examples cannot be built using a release NPM package of BokehJS as changes are +required which will not be released until BokehJS 4.0. +In the meantime the examples work using an NPM package produced using a particular Bokeh branch +which can be checked out and built in a temporary directory and the resultant NPM package copied +across to the root directory of this repository as follows. Note you will need `git` and `node` +installed. + +```bash +cd +git clone -b ianthomas23/13732_maybe_initialize --single-branch --depth 1 https://github.com/bokeh/bokeh.git +cd bokeh/bokehjs +node make build +npm pack +``` + +This will produce the file `bokeh-bokehjs-3.8.0-dev.1.tgz` which should be copied to the root +directory of your `bokehjs-examples` repository. diff --git a/recipes/README.md b/recipes/README.md index cd7b3c3..4343619 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -1,6 +1,6 @@ Code to create recipes. Each recipe is defined in a TypeScript class and can be written to both a -README markdown file for humans to follow, and a `bash` script that can be used to automatically -create the recipe. +`README.md` markdown file for humans to follow, and a `bash` script that can be used to +automatically create the recipe. To recreate all recipes: ```bash @@ -9,9 +9,12 @@ npm run build npm run create ``` -This will overwrite all existing recipes. If you are happy with the changes, `git commit` them. +This will overwrite all existing recipes. To recreate one or more named recipes rather than all of them use: ```bash npm run create -- VanillaWebpack VanillaRspack ``` + +Recipes should be recreated whenever any of the code within this directory or its subdirectories +is changed. From 7486693a30477008169140de628827a013b0c7c4 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Wed, 30 Apr 2025 11:34:09 +0100 Subject: [PATCH 2/3] Update --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index edbb752..66076f3 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,7 @@ and an image of the generated plot: Example plot - -## Contents +## Contents ### Examples From 288d8512d323230f64a673cbbda6fb3e248b5275 Mon Sep 17 00:00:00 2001 From: Ian Thomas Date: Wed, 30 Apr 2025 11:35:22 +0100 Subject: [PATCH 3/3] Update --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 66076f3..19fb174 100644 --- a/README.md +++ b/README.md @@ -93,3 +93,6 @@ npm pack This will produce the file `bokeh-bokehjs-3.8.0-dev.1.tgz` which should be copied to the root directory of your `bokehjs-examples` repository. + +When Bokeh and BokehJS 4.0 are released, these instructions and the code within this repository +will be updated to reflect the simpler installation process.