Skip to content

Commit ad70851

Browse files
bollwyvlbollwyvl
committed
remove travis config, split README/CONTRIBUTING
1 parent 8f9a7d5 commit ad70851

File tree

4 files changed

+234
-83
lines changed

4 files changed

+234
-83
lines changed

‎.travis.yml‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contributing
2+
3+
Thanks for contributing to pythreejs!
4+
5+
## Code Of Conduct
6+
7+
This project follows the [Project Jupyter Code of Conduct][coc].
8+
9+
[coc]: https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md
10+
11+
## Prerequisites
12+
13+
A full development environment will require:
14+
15+
- `python >=3.6`
16+
- `jupyterlab >=3`
17+
- once built, `jupyterlab` version `1` or `2` may be used
18+
- `nodejs >=12` e.g. via
19+
```bash
20+
conda install -c conda-forge 'nodejs>=12'
21+
```
22+
23+
## Development Tasks
24+
25+
The relevant commands while working on the repository are included below. These are not meant to be run sequentially, but rather as a list of useful commands.
26+
27+
Most of these tasks are executed on many platforms and clients in [continuous integration][ci]
28+
29+
[ci]: https://github.com/jupyter-widgets/pythreejs/blob/master/.github/workflows/ci.yml
30+
31+
### Clone
32+
33+
```bash
34+
git clone https://github.com/jupyter-widgets/pythreejs
35+
cd pythreejs
36+
```
37+
38+
### Dev setup
39+
40+
```bash
41+
python -m pip install -e .
42+
```
43+
44+
### Re-generate autogen files
45+
46+
```bash
47+
cd js
48+
npm run autogen
49+
```
50+
51+
> More about [autogen](#Autogen-update)
52+
53+
### Build and install JS distribution
54+
55+
```bash
56+
cd js
57+
npm run build:all
58+
jupyter nbextension install --py --symlink --sys-prefix pythreejs
59+
```
60+
61+
### Build the python distributions
62+
63+
```bash
64+
python setup.py sdist bdist_wheel
65+
```
66+
67+
### Clean out generated files
68+
69+
```bash
70+
cd js
71+
npm run clean
72+
```
73+
74+
### Symlink the JupyterLab 3 federated extension
75+
76+
```bash
77+
jupyter labextension develop . --overwrite
78+
```
79+
80+
### Run the tests
81+
82+
```bash
83+
python -m pip install -e .[test]
84+
pytest -vv -l --nbval-lax --current-env .
85+
```
86+
87+
### Build the docs
88+
89+
```bash
90+
python -m pip install -e .[docs]
91+
cd docs
92+
make html
93+
```
94+
95+
### Explore the examples
96+
97+
```bash
98+
python -m pip install -e .[examples]
99+
```
100+
101+
And then:
102+
103+
```
104+
jupyter notebook --debug
105+
# or
106+
jupyter lab --no-browser --debug
107+
```
108+
109+
### Watching sources
110+
111+
```bash
112+
cd js
113+
npm watch
114+
```
115+
116+
### Watching JupyterLab 3+ federated extension
117+
118+
```bash
119+
jupyter labextension watch .
120+
```
121+
122+
## Autogen update
123+
124+
This is a _significant_ re-work of the pythreejs extension that introduces an "autogen" script that generates the majority of the ipython-widget code to wrap each of three.js's types. It also takes a different view towards the pythreejs API. Whereas pythreejs adds custom functionality to the classes, sometimes renaming, etc., this approach attempts to mimic the low-level three.js API as closely as possible, opening up the possibility for others to build utility libraries on top of this.
125+
126+
The autogen script, `generate-wrappers.js`, takes advantage of a config file `three-class-config.js` to auto-generate both javascript and python files to define the ipywidget wrappers for each three.js class. The generated javascript files will have `.autogen.js` as the extension. The generated python files have `_autogen.py` as their extension. The script uses the handlebars template system to generate the various code files.
127+
128+
The autogen solution allows for overriding the default behavior of the generated classes. E.g., if `Object3D.js` is present, then it will be loaded into the namespace as opposed to loading `Object3D.autogen.js`. It is up to the author of the override classe to decide whether to inherit behavior from the autogen class or not. Same goes for the python modules. This allows for writing custom methods on both the python and javascript side when needed.
129+
130+
The autogen script relies on a json-like config file (`three-class-config.js`) to describe the classes. Reasonable defaults should take care of most, but it allows specifying the base class, constructor args, etc. for each of the wrappers. A base version of this file can be generated by `generate-class-config.js`, but beware, it overwrites any customization to the config file that has already been done.

‎README.md‎

Lines changed: 97 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,136 @@
11
# pythreejs
22

3-
4-
[![Documentation Status](https://readthedocs.org/projects/pythreejs/badge/?version=stable)](https://pythreejs.readthedocs.io/en/stable/?badge=stable)
5-
6-
7-
A Python / ThreeJS bridge utilizing the Jupyter widget infrastructure.
3+
[![Install from PyPI][pypi-badge]][pypi]
4+
[![Install from conda-forge][cf-badge]][cf]
5+
[![Documentation Status][docs-badge]][docs]
6+
[![Build Status][ci-badge]][ci]
7+
8+
A Python / ThreeJS bridge for [Jupyter Widgets][widgets].
9+
10+
[pypi-badge]: https://img.shields.io/pypi/v/pythreejs?logo=pypi
11+
[pypi]: https://pypi.org/project/pythreejs
12+
[cf-badge]: https://img.shields.io/conda/vn/conda-forge/pythreejs?logo=conda-forge
13+
[cf]: https://anaconda.org/conda-forge/pythreejs
14+
[docs-badge]: https://readthedocs.org/projects/pythreejs/badge/?version=stable
15+
[docs]: https://pythreejs.readthedocs.io/en/stable
16+
[ci-badge]: https://github.com/jupyter-widgets/pythreejs/actions/workflows/ci.yml/badge.svg
17+
[ci]: https://github.com/jupyter-widgets/pythreejs/actions/workflows/ci.yml?query=branch%3Amaster
18+
[widgets]: https://jupyter.org/widgets
819

920
![Screencast](screencast.gif)
1021

11-
## Getting Started
22+
## Installation
1223

13-
### Installation
14-
15-
Using pip:
24+
Using `pip`:
1625

1726
```bash
1827
pip install pythreejs
1928
```
2029

21-
And then install the extension for jupyter notebooks
30+
or `conda`:
31+
32+
```bash
33+
conda install -c conda-forge pythreejs
2234
```
35+
36+
> For a development install, see the [contributing guide][contributing].
37+
38+
The extension should then be installed automatically for your Jupyter client.
39+
40+
> For JupyterLab `<3`, you may also need to ensure `nodejs` is installed, and
41+
> rebuild the application:
42+
>
43+
> ```bash
44+
> # conda install -c cond-forge 'nodejs>=12'
45+
> jupyter lab build
46+
> ```
47+
48+
[contributing]: https://github.com/jupyter-widgets/pythreejs/blob/master/CONTRIBUTING.md
49+
50+
## Troubleshooting
51+
52+
If the extension is not automatically installed, you can manually enable it
53+
54+
### Jupyter Notebook Classic
55+
56+
```bash
57+
jupyter nbextension list
2358
jupyter nbextension install --py --symlink --sys-prefix pythreejs
2459
jupyter nbextension enable --py --sys-prefix pythreejs
60+
jupyter nbextension list
2561
```
2662
27-
Or for jupyter lab:
28-
```
29-
jupyter labextension install @jupyter-widgets/jupyterlab-manager
30-
jupyter labextension install jupyter-threejs
63+
You should see:
64+
65+
```bash
66+
Known nbextensions:
67+
...
68+
jupyter-js-widgets/extension enabled
69+
- Validating: OK
3170
```
3271

33-
Note for developers: the `--symlink` argument on Linux or OS X allows one to
34-
modify the JavaScript code in-place. This feature is not available
35-
with Windows.
72+
> Note for developers: the `--symlink` argument on Linux or MacOS allows one to
73+
> modify the JavaScript code in-place. This feature is not available on Windows.
74+
75+
### JupyterLab
3676

37-
Using conda
77+
To perform a _source installation_:
3878

3979
```bash
40-
conda install -c conda-forge pythreejs
80+
## ensure you have nodejs install, e.g. with conda
81+
# conda install -c conda-forge 'nodejs>=12'
82+
jupyter labextension list
83+
jupyter labextension install --no-build @jupyter-widgets/jupyterlab-manager
84+
jupyter labextension install --no-build jupyter-datawidgets/extension
85+
jupyter labextension install jupyter-threejs
86+
jupyter labextension list
4187
```
4288

89+
You should see:
4390

44-
## Developers
45-
46-
### Autogen update
91+
```bash
92+
JupyterLab v...
93+
...
94+
jupyterlab-datawidgets v... enabled OK
95+
@jupyter-widgets/jupyterlab-manager v... enabled OK
96+
jupyter-threejs v... enabled OK
4797

48-
This is a _significant_ re-work of the pythreejs extension that introduces an "autogen" script that generates the majority of the ipython-widget code to wrap each of three.js's types. It also takes a different view towards the pythreejs API. Whereas pythreejs adds custom functionality to the classes, sometimes renaming, etc., this approach attempts to mimic the low-level three.js API as closely as possible, opening up the possibility for others to build utility libraries on top of this.
98+
```
4999

50-
The autogen script, `generate-wrappers.js`, takes advantage of a config file `three-class-config.js` to auto-generate both javascript and python files to define the ipywidget wrappers for each three.js class. The generated javascript files will have `.autogen.js` as the extension. The generated python files have `_autogen.py` as their extension. The script uses the handlebars template system to generate the various code files.
100+
> This approach is _not recommended_ for JupyterLab 3, which enables
101+
> _federated modules_, installed via `pip`, `conda` or other package managers,
102+
> and does not require rebuilding the entire application.
51103
52-
The autogen solution allows for overriding the default behavior of the generated classes. E.g., if `Object3D.js` is present, then it will be loaded into the namespace as opposed to loading `Object3D.autogen.js`. It is up to the author of the override classe to decide whether to inherit behavior from the autogen class or not. Same goes for the python modules. This allows for writing custom methods on both the python and javascript side when needed.
104+
## Uninstallation
53105

54-
The autogen script relies on a json-like config file (`three-class-config.js`) to describe the classes. Reasonable defaults should take care of most, but it allows specifying the base class, constructor args, etc. for each of the wrappers. A base version of this file can be generated by `generate-class-config.js`, but beware, it overwrites any customization to the config file that has already been done.
106+
Using `pip`:
55107

56-
#### Setup
108+
```bash
109+
pip uninstall pythreejs
110+
```
57111

58-
The relevant commands while working on the repository are included below. These are not meant to be run sequentially, but rather as a list of useful commands:
112+
or `conda`:
59113

60114
```bash
61-
# To perform initial dev setup, run:
62-
pip install -e .
115+
conda uninstall pythreejs
116+
```
63117

64-
# All commands below assume to be in the ./js/ directory
65-
cd ./js/
118+
> If you applied any manual steps above, it may be necessary to remove the
66119
67-
# To re-generate autogen files, run:
68-
npm run autogen
120+
### Jupyter Notebook Classic
69121

70-
# To build and install distribution files, run:
71-
npm run build:all
72-
jupyter nbextension install --py --symlink --sys-prefix pythreejs
122+
```bash
123+
jupyter nbextension disable --py --sys-prefix pythreejs
124+
```
73125

74-
# To clean out generated files, run:
75-
npm run clean
126+
### Jupyter Lab
76127

77-
# To symlink the jupyter lab extension
78-
jupyter labextension develop .. --overwrite
128+
```bash
129+
jupyter labextension uninstall jupyter-threejs
130+
```
79131

132+
## Open Source
80133

81-
```
134+
This software is licensed under the [BSD-3-Clause][] License.
135+
136+
[bsd-3-clause]: https://github.com/jupyter-widgets/pythreejs/blob/master/LICENSE

‎setup.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,6 @@
1515
)
1616
import setuptools
1717

18-
19-
LONG_DESCRIPTION = 'A Python/ThreeJS bridge utilizing the Jupyter widget infrastructure.'
20-
2118
name = 'pythreejs'
2219
py_path = (HERE / name)
2320
js_path = (HERE / "js")
@@ -57,9 +54,13 @@
5754
setup_args = {
5855
'name': name,
5956
'version': version,
60-
'description': 'Interactive 3d graphics for the Jupyter notebook, using Three.js from Jupyter interactive widgets.',
61-
'long_description': LONG_DESCRIPTION,
62-
'license': 'BSD',
57+
'description': (
58+
'Interactive 3D graphics for the Jupyter Notebook and JupyterLab, '
59+
'using Three.js and Jupyter Widgets.'
60+
),
61+
'long_description': (HERE / "README.md").read_text(encoding="utf-8"),
62+
'long_description_content_type': 'text/markdown',
63+
'license': 'BSD-3-Clause',
6364
'include_package_data': True,
6465
'install_requires': [
6566
'ipywidgets>=7.2.1',

0 commit comments

Comments
 (0)