landscape-widget 0.2.0 → 0.3.0-alpha

package/README.md

@@ -0,0 +1,218 @@
+# jupyter-landscape
+
+Jupyter widget for interactive graph visualization. Supports live updates to
+colors and reports selected nodes back to the Python object.
+
+## Installation
+
+If you do not need to modify this package, the simplest way to get started is to
+download `environment.yml` and the built wheel from [the latest
+release](https://github.com/BlueLightAI/jupyter-landscapes/releases/latest).
+Then run the following:
+
+```sh
+conda env create -f environment.yml
+conda activate landscape-widget
+pip install landscape_widget-VERSION-py3-none-any.whl
+```
+
+If you are using this outside of conda, you will need to create a virtual
+environment manually and install the `mapper-core` dependency first:
+
+```sh
+# create and activate your virtual environment
+pip install git+https://github.com/BlueLightAI/mapper-core.git
+pip install landscape_widget-VERSION-py3-none-any.whl
+```
+
+This also applies if you want to use the package in a different conda
+environment than the one constructed from the `environment.yml` file.  One of
+the package's dependencies is `mapper-core`, which `pip` does not know how to
+resolve, so you need to install it manually.
+
+The widget is known to work in classic (version < 7) Jupyter notebooks, Jupyter
+Lab, and Visual Studio Code notebooks. Because it works in Jupyter Lab, it
+should work in notebook v7 as well, but this has not been tested. In order for a
+new or updated installation to be usable in VSCode, you will need to close and
+reopen the editor window hosting the notebooks.
+
+You may run into strange and unreliable widget behavior in some installations. A
+major source of these issues appears to be [this Jupyter
+bug](https://github.com/jupyter/notebook/issues/6721). The latest versions of
+the Jupyter dependencies do not seem to suffer from these problems.
+
+## Development Installation
+
+Clone the repository. Because this project uses a git submodule, you will need
+to do the following:
+
+```sh
+git clone --recurse-submodules https://github.com/BlueLightAI/jupyter-landscapes
+```
+
+Then create a new environment:
+
+```sh
+conda env create -f environment-dev.yml
+conda activate landscape-widget-dev
+```
+
+If you are using a non-conda environment, you will need an available
+installation of node, npm, and the yarn package manager, as well as (again),
+mapper-core.
+
+You will then need to build the `blai-graph-widget` package:
+
+```sh
+cd blai-graph-widget
+yarn install
+yarn build
+```
+
+If you update the files in this submodule (e.g. by changing to a different
+branch, or pulling new updates) you will need to repeat this step before
+building the main package again.
+
+Back in the root project directory, install the python package. This will also
+build the TypeScript code.
+
+```sh
+pip install -e ".[dev]"
+```
+
+This builds and installs both the Python and JavaScript portions of the widget.
+The Python code is installed in editable mode and will be automatically updated
+without the need to reinstall. However, if you change the TypeScript code, it
+will not update the extension by default (even if you run `yarn build`).
+Rerunning `pip install -e .` whenever you make a change to the frontend code is a
+safe way to work around this.
+
+Before committing any changes to the repo, install the pre-commit hooks and
+verify they run:
+
+```sh
+pre-commit install
+pre-commit run --all
+```
+
+If you want the JavaScript portion of the extension to automatically update when
+you rebuild, you will need to manually install the extension in an editable
+mode. Unfortunately, this interferes with the `pip install` process, so beware.
+To install the extension in editable mode for the classic notebook, run
+
+```sh
+jupyter nbextension install --sys-prefix --symlink --overwrite --py landscape_widget
+jupyter nbextension enable --sys-prefix --py landscape_widget
+```
+
+This replaces the `$SYS_PREFIX/share/jupyter/nbextensions/landscape_widget`
+directory with a symlink to the corresponding `landscape_widget/nbextension`
+directory in your source tree; this directory is repopulated whenever you run
+`yarn build`. (Note that because this relies on symlinks, it doesn't work on
+Windows, but I don't think anyone will be using that in the near future anyway.)
+Unfortunately, if you run `pip install` after doing this, it will run into a
+problem, because it first tries to remove the contents of that directory (which
+removes them from your source tree as well) and then tries to use your source
+tree to repopulate them. (In particular, this happens because there is a
+required file in this directory that is not built by the build process, and it
+gets deleted by pip but is never regenerated.) So to work around this, you will
+need to uninstall the extension before rerunning `pip install`:
+
+```sh
+jupyter nbextension uninstall --sys-prefix --py landscape_widget
+```
+
+These instructions currently seem to work for running the notebook in VSCode as well.
+
+Things should be a bit simpler for Jupyter Lab installation. The Python package
+must first be installed in editable mode. Then run
+
+```sh
+jupyter labextension develop --overwrite .
+yarn run build
+```
+
+This symlinks `landscape_widget/labextension` to the folder where Jupyter Lab
+expects the extension and rebuilds the extension.
+
+### How to see your changes
+
+Even when the package is installed in develop mode, you will need to restart the
+Jupyter kernel to see the effects of changes you have made to the Python code.
+(Using the magic `%load_ext autoreload` might work here, though.) Changes to the
+JavaScript code should appear after simply reloading the notebook page (although
+restarting the kernel doesn't hurt there either). In VSCode, you will need to
+close and reopen the editor window (not just the tab) in order to reload the JS
+code.
+
+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.
+
+```sh
+# Watch the source directory in one terminal, automatically rebuilding when needed
+yarn run watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+This should also work with `jupyter notebook` as long as the extension has been
+symlinked.
+
+After a change wait for the build to finish and then refresh your browser and
+the changes should take effect. You may prefer to manually run `yarn build`
+after making changes to the Typescript code, as the compilation process can be
+computationally intensive.
+
+### Using a dev version in another project
+
+To use an in-development version in another project (Cobalt, for instance), the
+process is similar. Find the file system path to the development directory for
+jupyter-landscapes, which we'll call `$WIDGET_PATH`. Then, from the development
+directory (and inside the correct Python virtual environment) for the other
+project, run the following:
+
+```sh
+pip install -e $WIDGET_PATH
+
+jupyter nbextension install --sys-prefix --symlink --overwrite --py landscape_widget
+jupyter nbextension enable --sys-prefix --py landscape_widget
+
+jupyter labextension develop --overwrite $WIDGET_PATH
+```
+
+Updates to the JavaScript portion of the widget will then be available in the
+other project as soon as they have been built.
+
+If for whatever reason you need to rerun the `pip install` step, run
+
+```sh
+jupyter nbextension uninstall --sys-prefix --py landscape_widget
+```
+first.
+
+### 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>
+```
+
+### License Report
+### `yarn build:license-report-json`
+### `yarn build:license-report-html`
+You can use the following commands to generate license reports in JSON and HTML formats.
+
+- `yarn build:license-report-json` will generate a `license-report.json` file in the root of the project, containing the license information for all project dependencies.
+- `yarn build:license-report-html` will generate a `license-report.html` file in the root of the project, containing the license information for all project dependencies.
+
+#### Adding Production-Only Option
+To generate a license report that includes only production packages, you can run the following commands with the `--only=prod` parameter:
+
+- `yarn build:license-report-json --only=prod` to generate a JSON report for production dependencies only.
+- `yarn build:license-report-html --only=prod` to generate an HTML report for production dependencies only.
+
+For more details, refer to the [license-report](https://www.npmjs.com/package/license-report) documentation.

package/css/widget.css

@@ -0,0 +1,8 @@
+.custom-widget {
+  padding: 5px;
+}
+
+.landscape-container {
+    height: 100%;
+    width: 100%;
+}