A monorepo containing jupyter-blocks and jupyter-tidyblocks. Blockly extension for JupyterLab.
Merge pull request #99 from QuantStack/docs
Update docs
authored by
Denisa Checiu
and committed by
GitHub
fafd1b1e
1f481174
+51
-29
+13
-1
docs/installation.md
+13
-1
docs/installation.md
···
12
12
conda install -c conda-forge jupyterlab-blockly
13
13
```
14
14
15
+
or
16
+
17
+
```bash
18
+
pip install jupyterlab-blockly
19
+
```
20
+
15
21
### Kernels
16
22
17
23
- ipykernel
···
28
34
conda uninstall -c conda-forge jupyterlab-blockly
29
35
```
30
36
37
+
or
38
+
39
+
```bash
40
+
pip uninstall jupyterlab-blockly
41
+
```
42
+
31
43
## Development install
32
44
33
45
**Note:** You will need NodeJS to build the extension package.
···
37
49
`yarn` or `npm` in lieu of `jlpm` below.
38
50
39
51
```bash
40
-
micromamba create -n blockly -c conda-forge python nodejs=18 yarn pre-commit jupyterla jupyter-packaging jupyterlab-language-pack-es-ES jupyterlab-language-pack-fr-FR ipykernel xeus-python xeus-lua
52
+
micromamba create -n blockly -c conda-forge python nodejs=18 yarn pre-commit jupyterla jupyterlab-language-pack-es-ES jupyterlab-language-pack-fr-FR ipykernel xeus-python xeus-lua
41
53
micromamba activate blockly
42
54
# Clone the repo to your local environment
43
55
# Change directory to the jupyterlab_blockly directory
+38
-28
docs/other_extensions.md
+38
-28
docs/other_extensions.md
···
3
3
The JupyterLab-Blockly extension is ready to be used as a base for other projects: you can register new Blocks, Toolboxes and Generators. It is a great tool for fast prototyping.
4
4
5
5
## Creating a new JupyterLab extension
6
-
You can easily create a new JupyterLab extension by using a `cookiecutter`. You can read more documentation about `cookiecutters` [here](https://cookiecutter.readthedocs.io/en/latest/), but the process is fairly straight-forward.
6
+
You can easily create a new JupyterLab extension by using the official `copier` template, documented [here](https://github.com/jupyterlab/extension-template).
7
7
8
-
After running the following command:
8
+
After installing the needed plugins (mentioned in the above link) and creating an extension directory, you can run the following command:
9
9
```
10
-
cookiecutter https://github.com/jupyterlab/extension-cookiecutter-ts
10
+
copier copy --trust https://github.com/jupyterlab/extension-template .
11
11
```
12
-
the `cookiecutter` will ask for some basic information about your project. Once completed, it will create a directory containing several files, all forming the base of your project. You will mostly work in the `index.ts` file, located in the `src` folder.
12
+
which will ask you to fill some basic information about your project. Once completed, the directory will be populated with several files, all forming the base of your project. You will mostly work in the `index.ts` file, located in the `src` folder.
13
13
14
-
An example of creating a simple JupyterLab extension, which also contains the instructions of how to fill the information asked by the `cookiecutter`, can be found [here](https://github.com/jupyterlab/extension-examples/tree/master/hello-world).
14
+
An example of creating a simple JupyterLab extension, which also contains the instructions of how to fill the information asked by the `copier` template, can be found [here](https://github.com/jupyterlab/extension-examples/tree/master/hello-world).
15
15
16
16
17
17
## Importing JupyterLab-Blockly
···
113
113
114
114
## Additional configurations
115
115
116
-
You will need to request the `jupyterlab-blockly` package as a dependency of your extension, in order to ensure it is installed and available to provide the token `IBlocklyRegistry`. To do this, you need to add the following line to your `setup.py` file.
116
+
You will need to request the `jupyterlab-blockly` package as a dependency for your extension, in order to ensure it is installed and available to provide the token `IBlocklyRegistry`. To do this, you need to add the following line to your `pyproject.toml` file.
117
117
118
-
```python
119
-
// setup.py : 57
118
+
```
119
+
// pyproject.toml : 26
120
120
121
-
setup_args = dict(
122
-
...
123
-
install_requires=['jupyterlab-blockly>=0.3.2,<0.4']
124
-
...
125
-
)
121
+
dependencies = [
122
+
"jupyterlab-blockly>=0.3.2,<0.4",
123
+
... // add any additional dependencies needed for your extension
124
+
]
126
125
```
127
126
128
-
Moreover, as we are working with deduplication of dependencies and the extension you are creating requires a service identified by a token from `jupyterlab-blockly`, you need to add the following configuration to your `package.json` file.
127
+
Additionally, you will need to add the webpack configuration for loading the `Blockly` source maps. You can do this, by creating the following `webpack.config.js` file inside your root directory:
128
+
129
+
```js
130
+
// @ts-check
129
131
132
+
module.exports = /** @type { import('webpack').Configuration } */ ({
133
+
devtool: 'source-map',
134
+
module: {
135
+
rules: [
136
+
// Load Blockly source maps.
137
+
{
138
+
test: /(blockly\/.*\.js)$/,
139
+
use: [require.resolve('source-map-loader')],
140
+
enforce: 'pre'
141
+
}
142
+
].filter(Boolean)
143
+
},
144
+
// https://github.com/google/blockly-samples/blob/9974e85becaa8ad17e35b588b95391c85865dafd/plugins/dev-scripts/config/webpack.config.js#L118-L120
145
+
ignoreWarnings: [/Failed to parse source map/]
146
+
});
130
147
```
131
-
// package.json : 88-101
132
148
149
+
and by connecting the `webpack` config to your `jupyterlab` instance, which entails adding the following line inside your `package.json`:
150
+
151
+
```json
133
152
"jupyterlab": {
134
-
"sharedPackages": {
135
-
"jupyterlab-blockly": {
136
-
"bundled": false,
137
-
"singleton": true
138
-
},
139
-
"blockly": {
140
-
"bundled": false,
141
-
"singleton": true
142
-
}
143
-
}
144
-
}
145
-
```
146
-
This ensures your extension will get the exact same token the provider is using to identify the service and exclude it from its bundle as the provider will give a copy of the token. You can read more about deduplication of dependencies [here](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#deduplication-of-dependencies), in the official *Extension Developer Guide for JupyterLab*.
153
+
...
154
+
"webpackConfig": "./webpack.config.js"
155
+
}
156
+
```