Skip to content

Commit 63c87b7

Browse files
terapyonterapyon
terapyon
authored and
terapyon
committed
update docs
1 parent eca2168 commit 63c87b7

File tree

7 files changed

+224
-57
lines changed

7 files changed

+224
-57
lines changed

‎README.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -20,17 +20,16 @@ This section provides a simple guide to get started with the project using Jupyt
2020

2121
### Example
2222

23-
```
23+
```python
2424
import net_vis
25+
2526
data = """
2627
{
2728
"nodes": [
2829
{
29-
"page_id": 1,
3030
"id": "Network"
3131
},
3232
{
33-
"page_id": 2,
3433
"id": "Graph"
3534
}
3635
],
@@ -47,56 +46,57 @@ w = net_vis.NetVis(value=data)
4746
w
4847
```
4948

50-
When executed, an SVG network graph is displayed.
49+
When executed, an interactive D3.js force-directed graph is displayed.
5150

5251
- Display Sample
5352

5453
![Desplay Sample](https://github.com/cmscom/netvis/blob/docs/source/_static/img/demo.png)
5554

55+
![JpyterLab Sample](https://github.com/cmscom/netvis/blob/docs/source/_static/img/net-vis-0.4.0.jpg)
56+
5657
## Development Installation
5758

5859
Create a dev environment:
5960

6061
```bash
61-
conda create -n net_vis-dev -c conda-forge nodejs python jupyterlab=4.0.11
62-
conda activate net_vis-dev
62+
python -m venv venv-netvis
63+
source venv-netvis/bin/activate
6364
```
6465

65-
Install the python. This will also build the TS package.
66+
Install the Python package. This will also build the TypeScript package:
6667

6768
```bash
68-
pip install -e ".[test, examples]"
69+
pip install -e ".[test, examples, docs]"
6970
```
7071

71-
When developing your extensions, you need to manually enable your extensions with the
72-
JupyterLab frontend. This is done by the command:
72+
Install JavaScript dependencies and build the extension:
7373

74-
```
74+
```bash
75+
yarn install
7576
jupyter labextension develop --overwrite .
76-
jlpm run build
77+
yarn run build
7778
```
7879

7980
**Note**: As of version 0.4.0, nbextension support has been removed. NetVis now exclusively uses the MIME renderer architecture for JupyterLab 3.x and 4.x.
8081

8182
### How to see your changes
8283

83-
#### Typescript:
84+
#### TypeScript:
8485

85-
If you use JupyterLab to develop then you can watch the source directory and run JupyterLab at the same time in different
86-
terminals to watch for changes in the extension's source and automatically rebuild the widget.
86+
If you use JupyterLab to develop, 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 extension.
8787

8888
```bash
8989
# Watch the source directory in one terminal, automatically rebuilding when needed
90-
jlpm run watch
90+
yarn run watch
9191
# Run JupyterLab in another terminal
9292
jupyter lab
9393
```
9494

95-
After a change wait for the build to finish and then refresh your browser and the changes should take effect.
95+
After a change, wait for the build to finish and then refresh your browser and the changes should take effect.
9696

9797
#### Python:
9898

99-
If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
99+
If you make a change to the Python code, you will need to restart the notebook kernel to have it take effect.
100100

101101
## Contributing
102102

‎docs/source/_static/img/net-vis-0.4.0.jpg‎

192 KB
Loading

‎docs/source/develop-install.rst‎

Lines changed: 47 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,60 @@ the repository::
99
git clone https://github.com/cmscom/netvis
1010
cd netvis
1111

12-
Next, install it with a develop install using pip::
12+
Create a development environment::
1313

14-
pip install -e .
14+
python -m venv venv-netvis
15+
source venv-netvis/bin/activate
1516

17+
Install the Python package with development dependencies::
1618

17-
If you are planning on working on the JS/frontend code, you should also do
18-
a link installation of the extension::
19+
pip install -e ".[test, examples, docs]"
1920

20-
jupyter nbextension install [--sys-prefix / --user / --system] --symlink --py net_vis
21+
Install JavaScript dependencies and set up the JupyterLab extension::
2122

22-
jupyter nbextension enable [--sys-prefix / --user / --system] --py net_vis
23+
yarn install
24+
jupyter labextension develop --overwrite .
25+
yarn run build
2326

24-
with the `appropriate flag`_. Or, if you are using Jupyterlab::
2527

26-
jupyter labextension install .
28+
Development workflow
29+
--------------------
2730

31+
TypeScript development
32+
^^^^^^^^^^^^^^^^^^^^^^
2833

29-
.. links
34+
To watch for changes and automatically rebuild the extension::
3035

31-
.. _`appropriate flag`: https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html#installing-and-enabling-extensions
36+
# Terminal 1: Watch TypeScript source
37+
yarn run watch
38+
39+
# Terminal 2: Run JupyterLab
40+
jupyter lab
41+
42+
After making changes, wait for the build to finish, then refresh your browser.
43+
44+
Python development
45+
^^^^^^^^^^^^^^^^^^
46+
47+
If you make changes to the Python code, restart the Jupyter kernel to see the effects.
48+
49+
50+
Running tests
51+
-------------
52+
53+
Run Python tests::
54+
55+
pytest -v
56+
57+
Run TypeScript tests::
58+
59+
yarn run test
60+
61+
Run linting::
62+
63+
yarn run lint:check
64+
python -m ruff check net_vis
65+
python -m pyright net_vis
66+
67+
68+
**Note**: As of version 0.4.0, nbextension support has been removed. NetVis now exclusively uses the MIME renderer architecture for JupyterLab 3.x and 4.x.

‎docs/source/examples/index.rst‎

Lines changed: 57 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,65 @@
22
Examples
33
========
44

5-
This section contains several examples generated from Jupyter notebooks.
6-
The widgets have been embedded into the page for demonstrative purposes.
5+
This section contains examples of using NetVis for interactive graph visualization in JupyterLab.
76

8-
.. todo::
7+
Basic Usage
8+
-----------
99

10-
Add links to notebooks in examples folder similar to the initial
11-
one. This is a manual step to ensure only those examples that
12-
are suited for inclusion are used.
10+
The most basic usage of NetVis::
11+
12+
import net_vis
13+
14+
data = """
15+
{
16+
"nodes": [
17+
{"id": "Node1"},
18+
{"id": "Node2"},
19+
{"id": "Node3"}
20+
],
21+
"links": [
22+
{"source": "Node1", "target": "Node2"},
23+
{"source": "Node2", "target": "Node3"}
24+
]
25+
}
26+
"""
27+
28+
vis = net_vis.NetVis(value=data)
29+
vis
30+
31+
Custom Node Properties
32+
-----------------------
33+
34+
You can customize node appearance with additional properties::
35+
36+
import net_vis
37+
38+
data = """
39+
{
40+
"nodes": [
41+
{"id": "A", "size": 10, "category": "type1"},
42+
{"id": "B", "size": 20, "category": "type2"},
43+
{"id": "C", "size": 15, "category": "type1"}
44+
],
45+
"links": [
46+
{"source": "A", "target": "B"},
47+
{"source": "B", "target": "C"}
48+
]
49+
}
50+
"""
51+
52+
vis = net_vis.NetVis(value=data)
53+
vis
54+
55+
Large Graphs
56+
------------
57+
58+
NetVis can handle large graphs efficiently. The force-directed layout automatically adjusts to the size of the graph.
59+
60+
61+
.. note::
62+
63+
For more examples, see the `examples directory <https://github.com/cmscom/netvis/tree/main/examples>`_ in the GitHub repository.
1364

1465

1566
.. toctree::

‎docs/source/index.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ net_vis
44

55
Version: |release|
66

7-
NetVis is a package for interactive visualization Python NetworkX graphs within Jupyter Lab. It leverages D3.js for dynamic rendering and supports HTML export, making network analysis effortless.
7+
NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering and supports HTML export, making network analysis effortless.
8+
9+
**Version 0.4.0** introduces a MIME renderer architecture that simplifies installation and improves compatibility with modern JupyterLab environments.
810

911

1012
Quickstart
@@ -14,9 +16,7 @@ To get started with net_vis, install with pip::
1416

1517
pip install net_vis
1618

17-
or with conda::
18-
19-
conda install net_vis
19+
**Note**: As of version 0.4.0, NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x. Manual extension enabling is no longer required.
2020

2121

2222
Contents

‎docs/source/installing.rst‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -9,29 +9,26 @@ The simplest way to install net_vis is via pip::
99

1010
pip install net_vis
1111

12-
or via conda::
12+
**That's it!** As of version 0.4.0, NetVis uses a MIME renderer that works automatically in JupyterLab 3.x and 4.x environments. No additional installation or configuration steps are required.
1313

14-
conda install net_vis
1514

15+
Requirements
16+
------------
1617

17-
If you installed via pip, and notebook version < 5.3, you will also have to
18-
install / configure the front-end extension as well. If you are using classic
19-
notebook (as opposed to Jupyterlab), run::
18+
- Python 3.10 or later
19+
- JupyterLab 3.x or 4.x
2020

21-
jupyter nbextension install [--sys-prefix / --user / --system] --py net_vis
21+
**Note**: Jupyter Notebook Classic is no longer supported as of version 0.4.0. Please use JupyterLab instead.
2222

23-
jupyter nbextension enable [--sys-prefix / --user / --system] --py net_vis
2423

25-
with the `appropriate flag`_. If you are using Jupyterlab, install the extension
26-
with::
24+
Upgrading from 0.3.x
25+
---------------------
2726

28-
jupyter labextension install net_vis
27+
If you're upgrading from version 0.3.x, please see the `MIGRATION.md <https://github.com/cmscom/netvis/blob/main/MIGRATION.md>`_ guide for detailed migration instructions.
2928

30-
If you are installing using conda, these commands should be unnecessary, but If
31-
you need to run them the commands should be the same (just make sure you choose the
32-
`--sys-prefix` flag).
29+
Key changes in 0.4.0:
3330

34-
35-
.. links
36-
37-
.. _`appropriate flag`: https://jupyter-notebook.readthedocs.io/en/stable/extending/frontend_extensions.html#installing-and-enabling-extensions
31+
- **Simplified installation**: No manual extension enabling required
32+
- **MIME renderer architecture**: Replaces ipywidgets-based rendering
33+
- **JupyterLab only**: Jupyter Notebook Classic is no longer supported
34+
- **Python API unchanged**: Your existing code will continue to work

‎docs/source/introduction.rst‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,88 @@
22
Introduction
33
=============
44

5-
.. todo::
5+
NetVis is a package for interactive visualization of Python NetworkX graphs within JupyterLab. It leverages D3.js for dynamic rendering, providing an intuitive and powerful way to explore and analyze network data.
66

7-
add prose explaining project purpose and usage here
7+
8+
Key Features
9+
------------
10+
11+
- **Interactive D3.js Visualization**: Force-directed graph layout with interactive node dragging, zooming, and panning
12+
- **Simple Python API**: Works seamlessly with NetworkX graph data structures
13+
- **MIME Renderer Architecture**: Automatic rendering in JupyterLab 3.x and 4.x without manual extension configuration
14+
- **Customizable Appearance**: Support for custom node colors, sizes, and categories
15+
- **Modern Stack**: Built with TypeScript and modern JupyterLab extension architecture
16+
17+
18+
Quick Example
19+
-------------
20+
21+
Here's a simple example to get you started::
22+
23+
import net_vis
24+
25+
data = """
26+
{
27+
"nodes": [
28+
{"id": "A"},
29+
{"id": "B"},
30+
{"id": "C"}
31+
],
32+
"links": [
33+
{"source": "A", "target": "B"},
34+
{"source": "B", "target": "C"}
35+
]
36+
}
37+
"""
38+
39+
w = net_vis.NetVis(value=data)
40+
w
41+
42+
When executed in JupyterLab, this displays an interactive force-directed graph where you can:
43+
44+
- **Drag nodes** to rearrange the layout
45+
- **Zoom and pan** to explore different areas
46+
- **Hover over nodes** to see labels
47+
- **Click nodes** to pin/unpin them
48+
49+
50+
Architecture (v0.4.0)
51+
---------------------
52+
53+
Version 0.4.0 introduces a major architectural change:
54+
55+
**MIME Renderer**
56+
NetVis now uses JupyterLab's MIME renderer system instead of ipywidgets. This means:
57+
58+
- Simpler installation (no manual extension enabling)
59+
- Better performance and integration with JupyterLab
60+
- Cleaner codebase with modern TypeScript
61+
62+
**JupyterLab Only**
63+
NetVis 0.4.0+ exclusively supports JupyterLab 3.x and 4.x. Jupyter Notebook Classic is no longer supported.
64+
65+
**Python API Unchanged**
66+
Despite the internal changes, the Python API remains 100% compatible with previous versions.
67+
68+
69+
What's New in 0.4.0
70+
-------------------
71+
72+
- **MIME renderer architecture** replacing ipywidgets
73+
- **Simplified installation** - just ``pip install net_vis``
74+
- **Removed nbextension support** - JupyterLab only
75+
- **Python 3.10+ support** including 3.13 and 3.14
76+
- **Comprehensive test suite** with 41 TypeScript tests and 16 Python tests
77+
- **Code quality tools** - ruff and pyright for Python linting and type checking
78+
79+
80+
Migrating from 0.3.x
81+
---------------------
82+
83+
If you're upgrading from version 0.3.x, your existing code will continue to work without changes. However, you should be aware that:
84+
85+
1. Jupyter Notebook Classic is no longer supported
86+
2. Manual extension enabling is no longer required
87+
3. Some internal APIs have changed (if you were using them directly)
88+
89+
For detailed migration instructions, see `MIGRATION.md <https://github.com/cmscom/netvis/blob/main/MIGRATION.md>`_.

0 commit comments

Comments
 (0)