docs: update README to better point to (#142)

* docs: make link to website more prominent Also make sure the index only links to parts of the README. * docs: add note regarding Node dependency when building from source * docs: add Node requirement to development section. Also add a note regarding anywidget's HMR * docs: add a note about how to run tests
flekschas · Aug 19, 2024 · b865e3c · b865e3c
1 parent 50eab6e
commit b865e3c
Showing 1 changed file with 43 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -43,34 +43,49 @@ Imagine trying to explore a dataset of millions of data points as a 2D scatter.
 
 Internally, Jupyter Scatter uses [regl-scatterplot](https://github.com/flekschas/regl-scatterplot/) for WebGL rendering, [traitlets](https://traitlets.readthedocs.io/en/stable/) for two-way communication between the JS and iPython kernels, and [anywidget](https://anywidget.dev/) for composing the widget.
 
+**Docs**
+
+Visit [https://jupyter-scatter.dev](https://jupyter-scatter.dev) for detailed documentation including examples and a complete API description.
+
+---
+
 **Index**
 
 1. [Install](#install)
 2. [Get Started](#get-started)
-3. [Docs](https://jupyter-scatter.dev)
-4. [Examples](notebooks/examples.ipynb)
-5. [Development](#development)
+   1. [Simplest Example](#simplest-example)
+   2. [Pandas DataFrame Example](#pandas-dataframe-example)
+   3. [Advanced Example](#advanced-example)
+   4. [Functional API Example](#functional-api-example)
+   5. [Linking Scatter Plots](#linking-scatter-plots)
+   6. [Visualize Millions of Data Points](#visualize-millions-of-data-points)
+   7. [Google Colab](#google-colab)
+4. [Development](#development)
+5. [Citation](#citation)
 
 ## Install
 
 ```bash
 pip install jupyter-scatter
 ```
 
-If you are using JupyterLab <=2:
+If you want to use Jupyter Scatter in JupyterLab <=2 you need to manually
+install it as an extension as follows:
 
 ```bash
 jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-scatter
 ```
 
+If you want to instal Jupyter Scatter from source, make sure to have [Node](https://nodejs.org) installed. While several version might work, we're primarily testing against the [Active LTS and Maintenance LTS releases](https://nodejs.org/en/about/previous-releases).
+
 For a minimal working example, take a look at [test-environments](test-environments).
 
 ## Get Started
 
 > [!TIP]
 > Visit [jupyter-scatter.dev](https://jupyter-scatter.dev) for details on all essential features of Jupyter Scatter and check out our [full-blown tutorial](https://github.com/flekschas/jupyter-scatter-tutorial) from SciPy '23.
 
-#### Simplest Example
+### Simplest Example
 
 In the simplest case, you can pass the x/y coordinates to the plot function as follows:
 
@@ -86,7 +101,7 @@ jscatter.plot(x, y)
 
 <img width="448" alt="Simplest scatter plotexample" src="https://user-images.githubusercontent.com/932103/116143120-bc5f2280-a6a8-11eb-8614-51def74d692e.png">
 
-#### Pandas Example
+### Pandas DataFrame Example
 
 Say your data is stored in a Pandas dataframe like the following:
 
@@ -119,7 +134,7 @@ jscatter.plot(data=df, x='mass', y='speed')
 <img width="448" alt="Pandas scatter plot example" src="https://user-images.githubusercontent.com/932103/116143383-1364f780-a6a9-11eb-974c-4facec249974.png">
 </details>
 
-#### Advanced example
+### Advanced Example
 
 Often you want to customize the visual encoding, such as the point color, size, and opacity.
 
@@ -144,7 +159,7 @@ Also notice how jscatter uses an appropriate color map by default based on the d
 
 You can, of course, customize the color map and many other parameters of the visual encoding as shown next.
 
-#### Functional API Example
+### Functional API Example
 
 The [flat API](#advanced-example) can get overwhelming when you want to customize a lot of properties. Therefore, jscatter provides a functional API that groups properties by type and exposes them via meaningfully-named methods.
 
@@ -167,7 +182,7 @@ Moreover, all arguments are optional. If you specify arguments, the methods will
 
 Finally, the scatter plot is interactive and supports two-way communication. Hence, if you select some point with the lasso tool and then call `scatter.selection()` you will get the current selection.
 
-#### Linking Scatter Plots
+### Linking Scatter Plots
 
 To explore multiple scatter plots and have their view, selection, and hover interactions link, use `jscatter.link()`.
 
@@ -184,7 +199,7 @@ https://user-images.githubusercontent.com/932103/162584133-85789d40-04f5-428d-b1
 
 See [notebooks/linking.ipynb](notebooks/linking.ipynb) for more details.
 
-#### Visualize Millions of Data Points
+### Visualize Millions of Data Points
 
 With `jupyter-scatter` you can easily visualize and interactively explore datasets with millions of points.
 
@@ -199,20 +214,19 @@ https://user-images.githubusercontent.com/932103/162586987-0b5313b0-befd-4bd1-8e
 
 See [notebooks/examples.ipynb](notebooks/examples.ipynb) for more details.
 
-#### Google Colab
+### Google Colab
 
 While jscatter is primarily developed for Jupyter Lab and Notebook, it also runs just fine in Google Colab. See [jupyter-scatter-colab-test.ipynb](https://colab.research.google.com/drive/195z6h6LsYpC25IIB3fSZIVUbqVlhtnQo?usp=sharing) for an example.
 
----
-
-### Development
+## Development
 
 <details><summary>Setting up a development environment</summary>
 <p>
 
 **Requirements:**
 
-- [Hatch](https://hatch.pypa.io/latest/) >= 1.7.0
+- [Hatch](https://hatch.pypa.io/latest/) >= v1.7.0
+- [Node](https://nodejs.org) [Active LTS or Maintenance LTS release](https://nodejs.org/en/about/previous-releases)
 
 **Installation:**
 
@@ -234,7 +248,12 @@ extension. To do so, run the following code at the beginning of a notebook:
 
 **After Changing JavaScript code:** do `cd js && npm run build`.
 
-Alternatively, you can run `npm run watch` and rebundle the code on the fly.
+Alternatively, you can enable anywidgets hot-module-reloading (HMR) as follows
+and run `npm run watch` to rebundle the JS code on the fly.
+
+```py
+%env ANYWIDGET_HMR=1
+```
 
 </p>
 </details>
@@ -247,6 +266,14 @@ Go to [test-environments](test-environments) and follow the instructions.
 </p>
 </details>
 
+<details><summary>Running tests</summary>
+<p>
+
+Run `pytest` after activating `hatch shell`.
+
+</p>
+</details>
+
 ## Citation
 
 If you use Jupyter Scatter in your research, please cite the following preprint: