From 31f736f64e5dc97907514fbd036906ab03bd0ce1 Mon Sep 17 00:00:00 2001 From: Thorsten Beier Date: Mon, 13 May 2024 10:20:57 +0200 Subject: [PATCH] extended docs (#940) --- .github/workflows/new_versions.yaml | 2 +- conda_build_config.yaml | 11 +--- docs/{ => development}/adding_packages.md | 0 docs/{ => development}/local_builds.md | 0 docs/project/related_projects.md | 34 +++++++++++ docs/usage/installing_packages.md | 18 ++++++ docs/usage/jupyterlite.md | 58 +++++++++++++++++++ mkdocs.yml | 1 + .../recipes_emscripten/astropy/recipe.yaml | 8 +-- .../awkward-cpp/recipe.yaml | 7 +-- .../ipython/recipe_legacy.yaml | 5 -- 11 files changed, 115 insertions(+), 29 deletions(-) rename docs/{ => development}/adding_packages.md (100%) rename docs/{ => development}/local_builds.md (100%) create mode 100644 docs/project/related_projects.md create mode 100644 docs/usage/installing_packages.md create mode 100644 docs/usage/jupyterlite.md diff --git a/.github/workflows/new_versions.yaml b/.github/workflows/new_versions.yaml index cc84b17be..966d7c163 100644 --- a/.github/workflows/new_versions.yaml +++ b/.github/workflows/new_versions.yaml @@ -21,4 +21,4 @@ jobs: shell: bash -l -eo pipefail {0} run: python -m emci bot bump-recipes-versions env: - GITHUB_TOKEN: ${{ secrets.BOT_ACCESS_TOKEN }} + GITHUB_TOKEN: ${{ secrets.BOT_ACCESS_TOKEN }} \ No newline at end of file diff --git a/conda_build_config.yaml b/conda_build_config.yaml index fbc87832f..84a8b3ddd 100644 --- a/conda_build_config.yaml +++ b/conda_build_config.yaml @@ -1,13 +1,4 @@ -#....... -# This differs from target_platform in that it determines what subdir the compiler -# will target, not what subdir the compiler package will be itself. -# For example, we need a win-64 vs2008_win-32 package, so that we compile win-32 -# code on win-64 miniconda. -cross_compiler_target_platform: # [win] - - win-64 # [win] - - -c_compiler: + dc_compiler: - if: emscripten then: - emscripten diff --git a/docs/adding_packages.md b/docs/development/adding_packages.md similarity index 100% rename from docs/adding_packages.md rename to docs/development/adding_packages.md diff --git a/docs/local_builds.md b/docs/development/local_builds.md similarity index 100% rename from docs/local_builds.md rename to docs/development/local_builds.md diff --git a/docs/project/related_projects.md b/docs/project/related_projects.md new file mode 100644 index 000000000..77e949234 --- /dev/null +++ b/docs/project/related_projects.md @@ -0,0 +1,34 @@ +# Related Projects + +## Pyodide + +[Pyodide](https://pyodide.org/en/stable/index.html) is a Python distribution for the browser and Node.js based on WebAssembly. +Emscripten-forge would not have been possible without the pioneering work of the pyodide team. +Many aspects of this project are heavily inspired by the pyodide project. This includes the build scripts and many of the patches which have been taken from the pyodide packages. + + +## pyjs +[pyjs](https://emscripten-forge.github.io/pyjs/) is modern pybind11 + emscripten Embind based Python <-> JavaScript foreign function interface (FFI) for wasm/emscripten compiled Python. +The API is loosly based on the FFI of pyodide. + +## pyjs-code-runner +[pyjs-code-runner](https://github.com/emscripten-forge/pyjs-code-runner) is a "driver" to run python code in a wasm environment, almost like running vanilla python code. This is used to run the tests of the emscripten-forge packages. + +## JupyterLite +[JupyterLite](https://jupyterlite.readthedocs.io/en/stable/) is a JupyterLab distribution that runs entirely in the browser built from the ground-up using JupyterLab components and extensions. + + +## JupyterLite Xeus + +[jupyterlite-xeus](https://github.com/jupyterlite/xeus) is a package/jupyterlite extension to use xeus-kernels +and packages from emscripten-forge in a jupyterlite environment. + + +## rattler-build + +[rattler-build](https://github.com/prefix-dev/rattler-build) is used to build the emscripten-forge packages + +## pixi + +[pixi](https://pixi.sh/latest/) is a package management tool for developers. It allows the developer to install libraries and applications in a reproducible way. +Emscripten-forge uses pixi to setup the environment for building the packages. \ No newline at end of file diff --git a/docs/usage/installing_packages.md b/docs/usage/installing_packages.md new file mode 100644 index 000000000..8e75d5cab --- /dev/null +++ b/docs/usage/installing_packages.md @@ -0,0 +1,18 @@ +#Installing packages + +## Install packages with micromamba +We recommend using micromamba to install packages from this channel. +To install micromamba itself, follow the instructions in the [micromamba documentation](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#micromamba-installation). + +To install packages from this channel, use the following command: + +```bash +micromamba create -n my-channel-name \ + --platform=emscripten-wasm32 \ + -c https://repo.mamba.pm/emscripten-forge \ + -c https://repo.mamba.pm/conda-forge \ + --yes \ + python numpy scipy matplotlib +``` + +All noarch packages are installed from the `conda-forge` channel, all packages compiled for the `emscripten-wasm32` platform are provided via the `emscripten-forge` channel. \ No newline at end of file diff --git a/docs/usage/jupyterlite.md b/docs/usage/jupyterlite.md new file mode 100644 index 000000000..408985af5 --- /dev/null +++ b/docs/usage/jupyterlite.md @@ -0,0 +1,58 @@ +# JupyterLite Xeus + + +## Installation + +To consume emscripten-forge packages in JupyterLite environment, the `jupyterlite_xeus` package needs +to be installed. This can be done with `pip` + +```bash +pip install jupyterlite_xeus +``` +or `conda`/`mamba`/`micromamba` + +``` +mamba install jupyterlite_xeus +``` + +## Usage + +!!! note + + Emscripten-forge provides xeus kernels for multiple languages, this document focuses on the Python kernel, namely `xeus-python`. + While the other kernels can also be installed as described below, adding custom packages is only supported for the `xeus-python` kernel + at the moment. + +### From environment file + +To load a xeus-python kernel with a custom environment, create an environment.yaml file with xeus-python and the desired dependencies. Here is an example with numpy as a additional dependency: +```yaml +name: xeus-lite-wasm +channels: + - https://repo.mamba.pm/emscripten-forge + - conda-forge +dependencies: + - xeus-python + - numpy +``` + +To build JupyterLite, run the following command where environment.yaml is the path to the file you just created + +```bash +jupyter lite build --XeusAddon.environment_file=some_path/to/environment.yaml +``` + +### From prefix +Create a environment with the desired packages. Here is an example with numpy as a additional dependency + +```bash +micromamba create + -n myenv \ + --platform=emscripten-wasm32 \ + -c https://repo.mamba.pm/emscripten-forge \ + -c conda-forge \ + --yes \ + "python>=3.11" numpy pandas xeus-python +``` + +jupyter lite build --XeusAddon.prefix=$MAMBA_ROOT_PREFIX/envs/myenv diff --git a/mkdocs.yml b/mkdocs.yml index 68925b20d..367f29938 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ theme: markdown_extensions: + - admonition - pymdownx.highlight: anchor_linenums: true line_spans: __span diff --git a/recipes/recipes_emscripten/astropy/recipe.yaml b/recipes/recipes_emscripten/astropy/recipe.yaml index f3ea74f30..5ea1294b8 100644 --- a/recipes/recipes_emscripten/astropy/recipe.yaml +++ b/recipes/recipes_emscripten/astropy/recipe.yaml @@ -31,10 +31,4 @@ requirements: - numpy - pyerfa - pyyaml - - packaging - -extra: - emscripten_tests: - python: - pytest_files: - - test_import_astropy.py + - packaging \ No newline at end of file diff --git a/recipes/recipes_emscripten/awkward-cpp/recipe.yaml b/recipes/recipes_emscripten/awkward-cpp/recipe.yaml index b2c37fa5d..ea692f282 100644 --- a/recipes/recipes_emscripten/awkward-cpp/recipe.yaml +++ b/recipes/recipes_emscripten/awkward-cpp/recipe.yaml @@ -49,9 +49,4 @@ about: homepage: https://pypi.org/project/awkward-cpp/ extra: recipe-maintainers: - - agoose77 - - emscripten_tests: - python: - pytest_files: - - test_import_awkward_cpp.py + - agoose77 \ No newline at end of file diff --git a/recipes/recipes_emscripten/ipython/recipe_legacy.yaml b/recipes/recipes_emscripten/ipython/recipe_legacy.yaml index bf3c4f169..ec540a5a6 100644 --- a/recipes/recipes_emscripten/ipython/recipe_legacy.yaml +++ b/recipes/recipes_emscripten/ipython/recipe_legacy.yaml @@ -49,10 +49,5 @@ about: dev_url: https://github.com/ipython/ipython extra: - emscripten_tests: - python: - pytest_files: - - test_ipython.py - recipe-maintainers: - DerThorsten