From 232b320f39a1593efac80fe05b6c7bd958028bd0 Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Wed, 14 Jan 2026 19:41:59 +0100 Subject: [PATCH 01/11] Update ci --- .github/workflows/docs.yml | 83 ++++++++------ .github/workflows/main.yml | 104 +++++------------- .../environment-dev.yml | 9 +- environments/environment-docs-wasm.yml | 8 ++ environments/environment-docs.yml | 20 ++++ environments/environment-wasm-test.yml | 8 ++ environments/environment-wasm.yml | 26 +++++ build_debug2.sh => scripts/build_debug2.sh | 0 build_mkdocs.sh => scripts/build_mkdocs.sh | 12 +- scripts/build_pyjs.sh | 36 ++++++ 10 files changed, 188 insertions(+), 118 deletions(-) rename environment-dev.yml => environments/environment-dev.yml (89%) create mode 100644 environments/environment-docs-wasm.yml create mode 100644 environments/environment-docs.yml create mode 100644 environments/environment-wasm-test.yml create mode 100644 environments/environment-wasm.yml rename build_debug2.sh => scripts/build_debug2.sh (100%) rename build_mkdocs.sh => scripts/build_mkdocs.sh (92%) create mode 100755 scripts/build_pyjs.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3dc945a..8cbd55c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,10 +3,9 @@ name: docs on: workflow_dispatch: push: + pull_request: branches: - main - # pull_request: - defaults: run: @@ -19,42 +18,64 @@ jobs: runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - include: - - emsdk_ver: "3.1.73" - python_version: "3.13" - - steps: - - uses: actions/checkout@v2 - - - name: Get number of CPU cores - uses: SimenB/github-actions-cpu-cores@v1 + - uses: actions/checkout@v6 - name: Install micromamba - uses: mamba-org/setup-micromamba@v1 + uses: mamba-org/setup-micromamba@v2 with: - environment-file: environment-dev.yml - environment-name: pyjs-wasm - condarc: | - channels: - - https://repo.mamba.pm/emscripten-forge-4x - - conda-forge - - - name: build the docs - shell: bash -el {0} + environment-file: environments/environment-docs.yml + environment-name: pyjs-docs + + - name: Create build directory for docs + run: mkdir docs_build + + - name: Convert *.py and *.js to *.ipynb using jupytext + run: | + mkdir -p docs_build/notebooks + + for f in examples/*.py; do + # get the filename without the extension and path + filename=$(basename -- "$f") + jupytext $f --to ipynb --output docs_build/notebooks/${filename%.*}.ipynb \ + --update-metadata '{"kernelspec": {"name": "xpython"}}' + done + for f in examples/*.js; do + # get the filename without the extension and path + filename=$(basename -- "$f") + jupytext $f --to ipynb --output docs_build/notebooks/${filename%.*}.ipynb \ + --update-metadata '{"kernelspec": {"name": "xjavascript"}}' + done + + - name: Create WASM environment for docs run: | - ./build_mkdocs.sh ${{matrix.emsdk_ver}} ${{ matrix.python_version }} - - ################################################################ - # upload to github pages - ################################################################ + micromamba create -n pyjs-docs-wasm \ + --platform=emscripten-wasm32 \ + -f environments/environment-docs-wasm.yml \ + --yes + + - name: Build the docs + run: | + mkdir docs_build/mkdocs + export PYTHONPATH=$PYTHONPATH:$(pwd)/stubs:$(pwd)/module + mkdocs build --site-dir=docs_build/mkdocs + + - name: Build JupyterLite + run: | + jupyter lite build \ + --contents=docs_build/notebooks \ + --output-dir docs_build/mkdocs/lite \ + --XeusAddon.prefix=$MAMBA_ROOT_PREFIX/envs/pyjs-docs-wasm + + - name: Copy pyjs binary + run: | + cp -v $MAMBA_ROOT_PREFIX/envs/pyjs-docs-wasm/lib_js/pyjs/* \ + docs_build/mkdocs/lite/xeus/bin/ + - name: Upload Pages artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v4 with: - path: docs_build/mkdocs + path: docs_build/mkdocs deploy: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 8fe8ef3..f30cf0c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -5,6 +5,8 @@ on: push: pull_request: +env: + PYTHON_VERSION: 3.13 defaults: run: @@ -21,124 +23,78 @@ jobs: fail-fast: false steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v6 - name: Install micromamba - uses: mamba-org/setup-micromamba@v1 + uses: mamba-org/setup-micromamba@v2 with: - environment-file: environment-dev.yml - environment-name: pyjs-wasm - condarc: | - channels: - - https://repo.prefix.dev/emscripten-forge-4x - - conda-forge - + environment-file: environments/environment-dev.yml + environment-name: pyjs-dev - name: Install Playwright run: | playwright install - - name: Build pyjs + - name: Create WASM environment to build pyjs run: | - micromamba activate pyjs-wasm - micromamba create -n pyjs-build-wasm \ --platform=emscripten-wasm32 \ - -c https://repo.prefix.dev/emscripten-forge-4x \ - -c https://repo.mamba.pm/conda-forge \ - --yes \ - "python=3.13" \ - "pybind11<3" \ - nlohmann_json pybind11_json numpy \ - pytest bzip2 sqlite zlib zstd libffi \ - exceptiongroup emscripten-abi>=4 \ - openssl liblzma - + -f environments/environment-wasm.yml \ + --yes - mkdir build - pushd build - - + - name: Build pyjs + run: | export PREFIX=$MAMBA_ROOT_PREFIX/envs/pyjs-build-wasm - export CMAKE_PREFIX_PATH=$PREFIX - export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX - - # build pyjs - emcmake cmake \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \ - -DBUILD_RUNTIME_BROWSER=ON \ - -DBUILD_RUNTIME_NODE=OFF \ - -DCMAKE_INSTALL_PREFIX=$PREFIX \ - .. + ./scripts/build_pyjs.sh $PREFIX - make -j2 - - make install - - popd - - - name: setup env with numpy + - name: Create test environment with numpy run: | - micromamba activate pyjs-wasm - micromamba create -n pyjs-build-wasm-with-numpy \ + micromamba create -n pyjs-wasm-test-with-numpy \ --platform=emscripten-wasm32 \ - -c https://repo.prefix.dev/emscripten-forge-4x \ - -c https://repo.mamba.pm/conda-forge \ - --yes \ - "python=3.13" pytest numpy exceptiongroup - + -f environments/environment-wasm-test.yml \ + numpy \ + --yes - - name: Test in browser-main + - name: Test browser-main with numpy run: | - micromamba activate pyjs-wasm pyjs_code_runner run script \ browser-main \ - --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-build-wasm-with-numpy \ + --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-wasm-test-with-numpy \ --mount $(pwd)/tests:/tests \ - --mount $(pwd)/module/pyjs:/lib/python3.13/site-packages/pyjs \ + --mount $(pwd)/module/pyjs:/lib/python${PYTHON_VERSION}/site-packages/pyjs \ --script main.py \ --work-dir /tests \ --pyjs-dir $(pwd)/build \ --headless \ --async-main - - name: Test in browser-worker + - name: Test browser-worker with numpy run: | - micromamba activate pyjs-wasm - - pyjs_code_runner run script \ browser-worker \ - --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-build-wasm-with-numpy \ + --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-wasm-test-with-numpy \ --mount $(pwd)/tests:/tests \ - --mount $(pwd)/module/pyjs:/lib/python3.13/site-packages/pyjs \ + --mount $(pwd)/module/pyjs:/lib/python${PYTHON_VERSION}/site-packages/pyjs \ --script main.py \ --work-dir /tests \ --pyjs-dir $(pwd)/build \ --headless \ --async-main - - name: setup minimal env without numpy + - name: Create test environment without numpy run: | - micromamba activate pyjs-wasm - micromamba create -n pyjs-build-wasm-no-numpy \ + micromamba create -n pyjs-wasm-test-no-numpy \ --platform=emscripten-wasm32 \ - -c https://repo.prefix.dev/emscripten-forge-4x \ - -c https://repo.mamba.pm/conda-forge \ - --yes \ - "python=3.13" pytest exceptiongroup + -f environments/environment-wasm-test.yml \ + --yes - - name: Test in browser-main-no-numpy + - name: Test browser-main without numpy run: | - micromamba activate pyjs-wasm - - pyjs_code_runner run script \ browser-main \ - --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-build-wasm-no-numpy \ + --conda-env $MAMBA_ROOT_PREFIX/envs/pyjs-wasm-test-no-numpy \ --mount $(pwd)/tests:/tests \ - --mount $(pwd)/module/pyjs:/lib/python3.13/site-packages/pyjs \ + --mount $(pwd)/module/pyjs:/lib/python${PYTHON_VERSION}/site-packages/pyjs \ --script main.py \ --work-dir /tests \ --pyjs-dir $(pwd)/build \ diff --git a/environment-dev.yml b/environments/environment-dev.yml similarity index 89% rename from environment-dev.yml rename to environments/environment-dev.yml index ef42e07..2ddf1c2 100644 --- a/environment-dev.yml +++ b/environments/environment-dev.yml @@ -1,12 +1,12 @@ -name: pyjs-wasm +name: pyjs-dev channels: - - conda-forge - https://repo.prefix.dev/emscripten-forge-4x - + - conda-forge dependencies: + - python == 3.13 + - emscripten_emscripten-wasm32 >= 4.0 - cmake - pip - - python - yarn - click - microsoft::playwright <= 1.50 @@ -28,7 +28,6 @@ dependencies: - notebook >=7,<8 # to include the extension to switch between JupyterLab and Notebook # pyjs_code_runner dev deps - hatchling - - emscripten_emscripten-wasm32 == 4.0.9 - pip: - JLDracula - pyjs_code_runner >= 3.0 diff --git a/environments/environment-docs-wasm.yml b/environments/environment-docs-wasm.yml new file mode 100644 index 0000000..3efa768 --- /dev/null +++ b/environments/environment-docs-wasm.yml @@ -0,0 +1,8 @@ +name: pyjs-docs-wasm +channels: + - https://repo.prefix.dev/emscripten-forge-4x + - conda-forge +dependencies: + - pyjs + - xeus-python + - xeus-javascript \ No newline at end of file diff --git a/environments/environment-docs.yml b/environments/environment-docs.yml new file mode 100644 index 0000000..f579035 --- /dev/null +++ b/environments/environment-docs.yml @@ -0,0 +1,20 @@ +name: pyjs-docs +channels: + - conda-forge +dependencies: + - jupytext + - mkdocs + - mkdocstrings + - mkdocstrings-python + - mkdocs-material + - empack >=6.0.0 + - jupyter_server # to enable contents + - jupyterlite + - jupyterlite-xeus >= 3.1.8 + - jupyterlite-sphinx + - notebook >=7,<8 # to include the extension to switch between JupyterLab and Notebook + # pyjs_code_runner dev deps + - hatchling + - pip: + - JLDracula + - pyjs_code_runner >= 3.0 diff --git a/environments/environment-wasm-test.yml b/environments/environment-wasm-test.yml new file mode 100644 index 0000000..d75769d --- /dev/null +++ b/environments/environment-wasm-test.yml @@ -0,0 +1,8 @@ +name: pyjs-wasm-test +channels: + - https://repo.prefix.dev/emscripten-forge-4x + - conda-forge +dependencies: + - python == 3.13 + - pytest + - exceptiongroup diff --git a/environments/environment-wasm.yml b/environments/environment-wasm.yml new file mode 100644 index 0000000..f9de8f6 --- /dev/null +++ b/environments/environment-wasm.yml @@ -0,0 +1,26 @@ +name: pyjs-wasm +channels: + - https://repo.prefix.dev/emscripten-forge-4x + - conda-forge +dependencies: + - python == 3.13 + - emscripten-abi >= 4.0 + - pybind11<3 + - pybind11_json + - nlohmann_json + - numpy + - bzip2 + - sqlite + - zlib + - zstd + - libffi + - exceptiongroup + - openssl + - liblzma + - xeus + - xeus-lite + - xeus-python + - xeus-javascript + - xtl + - ipython + - traitlets>=5.14.2 \ No newline at end of file diff --git a/build_debug2.sh b/scripts/build_debug2.sh similarity index 100% rename from build_debug2.sh rename to scripts/build_debug2.sh diff --git a/build_mkdocs.sh b/scripts/build_mkdocs.sh similarity index 92% rename from build_mkdocs.sh rename to scripts/build_mkdocs.sh index 19700a1..409b7b2 100755 --- a/build_mkdocs.sh +++ b/scripts/build_mkdocs.sh @@ -10,7 +10,7 @@ EMSDK_VERSION=$1 PYTHON_VERSION=$2 - + PYJS_PROBE_FILE=$WASM_ENV_PREFIX/lib_js/pyjs/pyjs_runtime_browser.js @@ -18,13 +18,9 @@ if [ ! -d "$WASM_ENV_PREFIX" ]; then echo "Creating wasm env $WASM_ENV_NAME" micromamba create -n $WASM_ENV_NAME \ --platform=emscripten-wasm32 \ - -c https://repo.prefix.dev/emscripten-forge-4x\ - -c https://repo.prefix.dev/conda-forge \ - --yes \ - python=$PYTHON_VERSION "pybind11<3" nlohmann_json pybind11_json numpy \ - bzip2 sqlite zlib zstd libffi exceptiongroup\ - "xeus" "xeus-lite" xeus-python "xeus-javascript" xtl "ipython" "traitlets>=5.14.2" \ - openssl liblzma + -f environment-wasm.yml \ + -n $WASM_ENV_NAME \ + --yes else echo "Wasm env $WASM_ENV_NAME already exists" diff --git a/scripts/build_pyjs.sh b/scripts/build_pyjs.sh new file mode 100755 index 0000000..a56a964 --- /dev/null +++ b/scripts/build_pyjs.sh @@ -0,0 +1,36 @@ +#!/bin/bash + +set -eux + +# Check if PREFIX argument is provided +if [ $# -eq 0 ]; then + echo "Usage: $0 " + echo "" + echo "Build pyjs with the specified installation prefix." + echo "" + echo "Arguments:" + echo " PREFIX Installation prefix path" + echo "" + exit 1 +fi + +PREFIX=$1 + +mkdir build +pushd build + +export CMAKE_PREFIX_PATH=$PREFIX +export CMAKE_SYSTEM_PREFIX_PATH=$PREFIX + +emcmake cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=ON \ + -DBUILD_RUNTIME_BROWSER=ON \ + -DBUILD_RUNTIME_NODE=OFF \ + -DCMAKE_INSTALL_PREFIX=$PREFIX \ + .. + +make -j2 +make install + +popd \ No newline at end of file From 67a0a0b648fd2c9b38ca7d223ad2888e62f08ddb Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Wed, 14 Jan 2026 19:46:12 +0100 Subject: [PATCH 02/11] Add default channels --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8cbd55c..cd06c59 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -65,6 +65,7 @@ jobs: jupyter lite build \ --contents=docs_build/notebooks \ --output-dir docs_build/mkdocs/lite \ + --XeusAddon.default_channels=["https://repo.prefix.dev/emscripten-forge-4x", conda-forge] \ --XeusAddon.prefix=$MAMBA_ROOT_PREFIX/envs/pyjs-docs-wasm - name: Copy pyjs binary From 89c7df7697b9345f6a6917aa4595fe78465e140e Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Wed, 14 Jan 2026 19:50:25 +0100 Subject: [PATCH 03/11] Fix pin --- environments/environment-wasm.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/environments/environment-wasm.yml b/environments/environment-wasm.yml index f9de8f6..b18dc0c 100644 --- a/environments/environment-wasm.yml +++ b/environments/environment-wasm.yml @@ -3,7 +3,7 @@ channels: - https://repo.prefix.dev/emscripten-forge-4x - conda-forge dependencies: - - python == 3.13 + - python=3.13 - emscripten-abi >= 4.0 - pybind11<3 - pybind11_json From b01bc42f071173eb44a63f033563ada357a397e4 Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Wed, 14 Jan 2026 19:55:52 +0100 Subject: [PATCH 04/11] Fix all the pins --- environments/environment-dev.yml | 2 +- environments/environment-wasm-test.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/environments/environment-dev.yml b/environments/environment-dev.yml index 2ddf1c2..4137fb4 100644 --- a/environments/environment-dev.yml +++ b/environments/environment-dev.yml @@ -3,7 +3,7 @@ channels: - https://repo.prefix.dev/emscripten-forge-4x - conda-forge dependencies: - - python == 3.13 + - python=3.13 - emscripten_emscripten-wasm32 >= 4.0 - cmake - pip diff --git a/environments/environment-wasm-test.yml b/environments/environment-wasm-test.yml index d75769d..4b7e8de 100644 --- a/environments/environment-wasm-test.yml +++ b/environments/environment-wasm-test.yml @@ -3,6 +3,6 @@ channels: - https://repo.prefix.dev/emscripten-forge-4x - conda-forge dependencies: - - python == 3.13 + - python=3.13 - pytest - exceptiongroup From 5dfb4542d8cd964b8c230f436f8bba8478564c8f Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Wed, 14 Jan 2026 19:56:33 +0100 Subject: [PATCH 05/11] Check files --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index cd06c59..50170b0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -70,6 +70,7 @@ jobs: - name: Copy pyjs binary run: | + ls -al $MAMBA_ROOT_PREFIX/envs/pyjs-docs-wasm/ cp -v $MAMBA_ROOT_PREFIX/envs/pyjs-docs-wasm/lib_js/pyjs/* \ docs_build/mkdocs/lite/xeus/bin/ From 5cac5e8c53bdebdf2f38461f7363a1162d8e1cef Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Thu, 15 Jan 2026 16:54:29 +0100 Subject: [PATCH 06/11] Filter by paths --- .github/workflows/docs.yml | 6 ++++-- .github/workflows/main.yml | 4 ++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 50170b0..c014180 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,9 +3,11 @@ name: docs on: workflow_dispatch: push: + paths: + - 'docs/**' pull_request: - branches: - - main + paths: + - 'docs/**' defaults: run: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f30cf0c..01dcc26 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -3,7 +3,11 @@ name: CI on: workflow_dispatch: push: + paths-ignore: + - 'docs/**' pull_request: + paths-ignore: + - 'docs/**' env: PYTHON_VERSION: 3.13 From bf0f28102ed5e8bb8006d79b214ccc3f52050b8f Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Thu, 15 Jan 2026 16:59:02 +0100 Subject: [PATCH 07/11] Trigger when push to main only --- .github/workflows/docs.yml | 2 ++ .github/workflows/main.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c014180..1ba1549 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,6 +3,8 @@ name: docs on: workflow_dispatch: push: + branches: + - main paths: - 'docs/**' pull_request: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 01dcc26..e6191ca 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -3,6 +3,8 @@ name: CI on: workflow_dispatch: push: + branches: + - main paths-ignore: - 'docs/**' pull_request: From a2827b62a6aa6cb224c7d30e7a2b993a7fc70e6b Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Thu, 15 Jan 2026 17:00:55 +0100 Subject: [PATCH 08/11] Update channel in docs --- docs/installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 3b15895..4e24690 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -17,21 +17,21 @@ So we assume there is a directory called `/path/to/deploy` where we will put all tools which need to be served to the user. ### Define a conda environment -Pyjs has a conda-like workflow. This means the first step +Pyjs has a conda-like workflow. This means the first step is to create a environment with the `pyjs` package installed and all packages required for the project. ```yaml -name: my-pyjs-env +name: my-pyjs-env channels: - - https://repo.prefix.dev/emscripten-forge-dev + - https://repo.prefix.dev/emscripten-forge-4x - https://repo.prefix.dev/conda-forge dependencies: - pyjs - numpy ``` -The name of the environment can be choosen by the user. +The name of the environment can be chosen by the user. The `channels` section specifies the conda channels to use. The `https://repo.mamba.pm/emscripten-forge` is mandatory to install the `pyjs` package. The `conda-forge` channel is used to install `noarch`. From f185ac89edf06e74b1b6a7558f385de11a551979 Mon Sep 17 00:00:00 2001 From: Isabel Paredes Date: Thu, 15 Jan 2026 18:21:37 +0100 Subject: [PATCH 09/11] Update docs --- docs/design.md | 4 +-- docs/index.md | 16 +++++------ docs/installation.md | 64 +++++++++++++++++++++++++------------------- docs/try_from_js.md | 4 +-- docs/try_from_py.md | 4 +-- 5 files changed, 50 insertions(+), 42 deletions(-) diff --git a/docs/design.md b/docs/design.md index c8a090f..a9843b7 100644 --- a/docs/design.md +++ b/docs/design.md @@ -2,7 +2,7 @@ ## Main Idea ### pybind11 -[Pybind11](https://github.com/pybind/pybind11) is a library that exposes C++ types in Python. It is a wrapper around the Python C API that allows for seamless integration of C++ and Python. +[Pybind11](https://github.com/pybind/pybind11) is a library that exposes C++ types in Python. It is a wrapper around the Python C API that allows for seamless integration of C++ and Python. To export a C++ class like the following to Python, you would use pybind11: ```C++ @@ -27,7 +27,7 @@ PYBIND11_MODULE(example, m) { } ``` Not only can Python call C++ functions, but C++ can also call Python functions. In particular, one can interact -with Python objects. An object is represented by the `py::object` type on the C++ side. +with Python objects. An object is represented by the `py::object` type on the C++ side. ```C++ // main.cpp diff --git a/docs/index.md b/docs/index.md index 5e74a38..2153d4a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,17 @@ # Welcome to `pyjs` -Pyjs is a python - javascript FFI for webassembly. -It allows you to write python code and run it in the browser. +Pyjs is a Python - JavaScript FFI for WebAssembly. +It allows you to write python code and run it in the browser. -## Quickstart +## Quick Start -Access Javascript from Python: +Access JavaScript from Python: ```python import pyjs -# hello world +# hello world pyjs.js.console.log("Hello, World!") # create a JavaScript function to add two numbers @@ -24,7 +24,7 @@ js_function = pyjs.js.Function("a", "b", """ result = js_function(1, 2) ``` -Access Python from Javascript: +Access Python from JavaScript: ```JavaScript // hello world @@ -33,11 +33,11 @@ pyjs.eval("print('Hello, World!')") // eval a python expression and get the result const py_list = pyjs.eval("[i for i in range(10)]") -/// access +/// access console.log(py_list.get(0)) // same as py_list[0] on the python side ``` -## Try it out +## Try it out! To try it out, you can use [jupyterlite](../lite), the [JavaScript REPL](try_from_js) or the [Python REPL](try_from_py). \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index 4e24690..f163f42 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,25 +1,28 @@ # Deploying pyjs -## Prerequisites: +## Prerequisites Before we start, lets introduce a few concepts and tools that are used in the pyjs workflow. -### Conda-forge Emscripten-Forge -[Emscripten-forge](https://github.com/emscripten-forge/recipes) is similar to [conda-forge](https://conda-forge.org/) and provides packages compiled to webassembly using emscripten. +### Emscripten-forge + +Similar to [conda-forge](https://conda-forge.org/), [emscripten-forge](https://github.com/emscripten-forge/recipes) provides packages which are compiled to WebAssembly using [Emscripten](https://emscripten.org/). ### Empack -https://github.com/emscripten-forge/empack is a tool to "pack" conda environments into a set of files that can be consumed by pyjs. +[Empack](https://github.com/emscripten-forge/empack) is a tool to "pack" conda environments into a set of files that can be consumed by pyjs. +```bash +micromamba install empack -c conda-forge +``` ## Installation Steps -So we assume there is a directory called `/path/to/deploy` where we will -put all tools which need to be served to the user. -### Define a conda environment +### 1. Define a conda environment Pyjs has a conda-like workflow. This means the first step -is to create a environment with the `pyjs` package installed -and all packages required for the project. +is to define a WebAssembly environment that includes `pyjs` and any other packages required for your project. + +Create an *environment.yml* file with the following: ```yaml name: my-pyjs-env @@ -31,30 +34,35 @@ dependencies: - numpy ``` -The name of the environment can be chosen by the user. -The `channels` section specifies the conda channels to use. -The `https://repo.mamba.pm/emscripten-forge` is mandatory to install the `pyjs` package. -The `conda-forge` channel is used to install `noarch`. -All compiled packages need to be available in the `emscripten-forge` channel. +- The `name` of the environment can be chosen by the user. +- The `channels` section specifies the conda channels to use. +- The `https://repo.prefix.dev/emscripten-forge-4x` is mandatory to install the `pyjs` package. +- The `conda-forge` channel is used to install `noarch` packages. + -### Create the environment -Assuming the yaml file above is called `environment.yml` and is in the current directory, the environment can be created using `micromamba`: +Please note, all compiled packages need to be available in the [`emscripten-forge-4x`](https://prefix.dev/channels/emscripten-forge-4x) channel. + +### 2. Create the environment +The environment can be created using `micromamba`: ```Bash micromamba create -f environment.yml --platform emscripten-wasm32 --prefix /path/to/env ``` -### Copy pyjs +### 3. Populate the directory to be deployed + +Create a deploy directory, */path/to/deploy/*, where we will +put all of the tools needed to be served to the user. + Copy the pyjs binary from the environment to the deploy directory. -This should move pyjs_runtime_browser.js and pyjs_runtime_browser.wasm to the deployment directory. +This will move *pyjs_runtime_browser.js* and *pyjs_runtime_browser.wasm* to the deployment directory. ```Bash -cp /path/to/env/lib_js/pyjs/* /path/to/deploy +cp /path/to/env/lib_js/pyjs/* /path/to/deploy/ ``` - -### Pack the environment +### 4. Pack the environment After the environment is defined, the next step is to pack the environment using `empack`. @@ -64,31 +72,31 @@ empack pack env --env-prefix /path/to/env --outdir /path/to/deploy This will create a tarball for each package in the environment and a `empack_env_meta.json` file that describes the environment. -### The html/JavaScript code +### 5. Add the HTML/JavaScript code -The last step is to create a html file that loads the pyjs runtime and the packed environment. +The last step is to create an html file that loads the pyjs runtime and the packed environment. ```html Pyjs Example - +