dotdata_widgets 0.1.9 → 0.2.0

package/README.md

@@ -1,119 +1,86 @@
-# Dotdata widgets
+# Dotdata Widgets
 
-A dotdata widget
+Dotdata widgets consist of a NodeJS library and a python module.
 
-### Prerequisites
+## Building the `nodejs` part
 
-1. nodejs >= 18
-2. yarn (npm install yarn -g)
-3. python 3
-
-## Installation
-
-You can install using `pip`:
-
-```bash
-pip install dotdata_widgets
-```
-
-If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable
-the nbextension:
+In order to build the nodejs part of dotdata widgets - follow the `make` targets
+defined in the `Makefile` in this directory.
 
 ```bash
-jupyter nbextension enable --py [--sys-prefix|--user|--system] dotdata_widgets
+make build_js
 ```
-
-## Development Installation
-
-Create a dev environment:
-
-```bash
-python -m venv venv/
-```
-
-Install the python. This will also build the TS package.
-
+There is an alias for this command in the root-level `Makefile`:
 ```bash
-pip install -e ".[test, examples]"
-```
-
-When developing your extensions, you need to manually enable your extensions with the
-notebook / lab frontend. For lab, this is done by the command:
-
-```
-jupyter labextension develop --overwrite .
-yarn run build
+make -C ../../ build_widgets_js_for_iff
 ```
 
-For classic notebook, you need to run:
-
-```
-jupyter nbextension install --sys-prefix --symlink --overwrite --py dotdata_widgets
-jupyter nbextension enable --sys-prefix --py dotdata_widgets
-```
+NOTE: this command might not work if on platforms other than linux.
+The docker container in which the commands are executed is based on `node:18.15` container,
+which assumes that the working user has `UID=1000`.
+Calling it on MacOS may produce artifacts with invalid ownership.
 
-Note that the `--symlink` flag doesn't work on Windows, so you will here have to run
-the `install` command every time that you rebuild your extension. For certain installations
-you might also need another flag instead of `--sys-prefix`, but we won't cover the meaning
-of those flags here.
+In order to build the nodejs package without the docker, make sure you've provisioned your local environment
+as described in the `docker/npm/Dockerfile`. Especially make sure that you have:
 
-### Watch Mode
+* node in version >=18
+* yarn (`npm install yarn -g`)
+* python >=3.8
+* jupyterlab
 
+Then you may call:
 ```bash
-yarn run watch
+make -C ../../ build_js_without_docker
 ```
 
-### Docker
-
-```bash
-git clone ...
-
-docker run -it --name dotdata_widget -v $(pwd)/dotdata_widgets:/dotdata_widgets -p 8889:8888 jupyter/scipy-notebook
-```
-
-### How to see your changes
-
-#### Typescript:
-
-If you use JupyterLab to develop then you can watch the source directory and run JupyterLab at the same time in
-different
-terminals to watch for changes in the extension's source and automatically rebuild the widget.
-
-```bash
-# Watch the source directory in one terminal, automatically rebuilding when needed
-yarn run watch
-# Run JupyterLab in another terminal
-jupyter lab
-```
-
-After a change wait for the build to finish and then refresh your browser and the changes should take effect.
-
-#### Python:
-
-If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
-
-## Updating the version
-
-To update the version, install tbump and use it to bump the version.
-By default it will also create a tag.
-
-```bash
-pip install tbump
-tbump <new-version>
-```
-
-## Build with docker
-
-```bash
-# Only for the first run
-docker build -t dotdata_widgets_builder .
-
-# bump version before run
-docker run -it --rm --env VERSION=0.1.2 -v $(pwd):/dotdata_widgets dotdata_widgets_builder
-```
-
-## Publish npm package
-
-```bash
-npm publish
-```
+## Publishing the js part of Dotdata Widgets
+
+**DO NOT publish the nodejs package unless you're sure what you're doing!**
+
+Dotdata Widgets are published in a public npm repository.
+You can browse the published packages at https://www.npmjs.com/package/dotdata_widgets
+
+Dotdata widgets are published together with the dotdata wheel by the jenkins job,
+which calls `make publish_iff` from the root-level `Makefile`.
+This command refers to the npm `publish` command, which utilises credentials to npm registry
+defined in `.npmrc`
+
+
+## Interactive development and testing
+
+**WARNING: THERE ARE NO AUTOMATED TESTS OF DOTDATA WIDGETS (neither JS nor python part).**
+
+Dotdata widgets can be tested manually in a jupyter notebook.
+
+In order to do so do the following:
+* Prune local virtual env:
+  ```bash
+  make -C ../../ prune_iff_test_env
+  ```
+  This command cleans the venv directory and deletes pre-existing artifacts.
+* Install `dotdata` in dev mode in the local virtual env:
+  ```bash
+  make -C ../../ prepare_iff_interactive_dev_env
+  ```
+  This command installs `jupyterlab`, installs `dotdata` in `--editable` mode, and calls `jupyter labextension develop --overwrite ${PATH_TO_DOTDAT_WIDGETS}`.
+  Although it make take up to 20 minutes, it has to be called only once.
+* Launch widgets compilation server:
+  ```bash
+  make -C ../../ _run_yarn_watch_compilation_of_dotdata_widgets
+  ```
+  * NOTE: this command requires `node` and `yarn` to be installed in your environment.
+  * Also, it fails if `prepare_iff_interactive_dev_env` wasn't called before.
+  * This command spawns a server that watches for changes in the ts files and recompiles them on the fly.
+  * Run it in separate terminal.
+  * A single recompilation may take up to a minute, so be patient.
+* Launch jupyter lab:
+  ```bash
+  make -C ../../ _start_jupyterlab
+  ```
+  * This command spawns a jupyter-lab server. Run it in separate terminal.
+  * It also opens a browser window with a jupyter lab workspace.
+* Open a notebook (e.g. `examples/introduction.ipynb`) and work with your widgets.
+
+When developing widgets in interactive mode, keep in mind that:
+* you have to reload browser caches in order to force it to load re-compiled `*.js` files.
+* you have to restart notebook's kernel in order to load modified python modules.

package/css/widget.css

@@ -3,7 +3,7 @@
 @import url('colors.css');
 @import url('typography.css');
 
-@import url('../src/feature-descriptor/feature-descriptors-domain.css');
+@import url('../src/feature-descriptor/feature-descriptors.css');
 @import url('../src/components/accordion/accordion.css');
 @import url('../src/widgets/feature-space/feature-space.css');
 @import url('../src/widgets/feature-leaderboard/feature-leaderboard.css');