JupyterLite 项目开发环境搭建与贡献指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00926/article/details/148549021

JupyterLite 项目开发环境搭建与贡献指南

jupyterlite Wasm powered Jupyter running in the browser 💡 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlite

前言

JupyterLite 是一个基于 WebAssembly 的轻量级 Jupyter 环境，可以在浏览器中直接运行，无需服务器后端。本文将详细介绍如何搭建 JupyterLite 的开发环境，以及项目中的核心开发流程。

开发环境准备

基础环境要求

在开始 JupyterLite 开发前，需要确保系统满足以下基本要求：

Git 版本控制系统
Node.js 20.x 版本（但不包括 21.x）
JupyterLab 4.5.0a1 或更高版本（但低于 4.6）
Python 3.12.x 版本

代码获取

使用 Git 克隆项目仓库：

git clone https://github.com/jupyterlite/jupyterlite

开发工具链

核心工具 doit

JupyterLite 使用 doit 作为构建工具，它管理着从 JavaScript 构建到文档生成的整个软件生命周期。doit 能够理解不同任务之间的依赖关系，通常以磁盘上文件的变更作为触发条件。

常用 doit 命令

初始化开发环境：
```
doit dev
```
查看所有可用任务：
```
doit list --all --status
```
默认构建任务（等同于直接运行 doit）：
```
doit build docs:app:build
```

开发服务器

JupyterLite 提供了多种开发服务器选项：

核心资产服务器（端口 5000）：
- JavaScript 版本：doit serve:core:js
- Python 版本：doit serve:core:py
示例文档站点（端口 8000）：
```
doit serve:docs:app
```
可通过 LITE_ARGS 环境变量传递 CLI 参数
JupyterLab 服务器（端口 8888）：
```
doit serve:lab
```
可通过 LAB_ARGS 环境变量传递 CLI 参数

JavaScript 开发工作流

快速开始

一键初始化 JavaScript 开发环境：

jlpm bootstrap

核心构建流程

安装依赖：
```
jlpm
```
开发构建：
```
jlpm build
```
生产构建：
```
jlpm build:prod
```
启动开发服务器：
- Node.js 版本：jlpm serve
- Python 版本：jlpm serve:py
文件监视模式：
```
jlpm watch
```

代码质量工具

代码格式化与检查：
```
jlpm lint
```
单元测试：
```
jlpm build:test
jlpm test
```

Python 开发工作流

内核扩展

默认只包含 JavaScript 内核，如需添加其他内核：

Pyodide 内核：
```
pip install jupyterlite-pyodide-kernel
```
Xeus Python 内核：需要参考 Xeus 项目的安装文档

测试配置

可以通过环境变量传递额外的 pytest 参数：

PYTEST_ARGS='["-s", "-x", "--ff"]' doit test:py:jupyterlite-core

UI 测试框架

JupyterLite 使用基于 Playwright 的 Galata 框架进行端到端和视觉回归测试。

测试流程

安装依赖：
```
cd ui-tests
jlpm install
```
构建测试环境：
```
jlpm build
```
运行测试：
```
jlpm test
```

视觉回归测试

生成参考快照：
```
jlpm test:update
```
更新快照流程：
- 提交代码变更
- 等待 CI 完成
- 下载更新后的快照文件
- 替换本地快照目录
- 提交更新

问题排查

测试失败时，可以：

下载 Playwright 报告
启动本地服务器查看报告
检查失败测试的 Trace 部分

文档系统

JupyterLite 文档使用 Sphinx 构建，部分内容使用可执行的 Jupyter Notebook 编写。

文档构建

完整构建：
```
doit docs
```
开发监视模式：
```
doit watch:docs
```
严格模式构建（用于 CI）：
```
SPHINX_ARGS='["-W"]' doit docs
```

结语

本文详细介绍了 JupyterLite 项目的开发环境搭建和核心开发流程。通过合理利用项目提供的工具链，开发者可以高效地参与项目贡献。建议新贡献者从简单的文档改进或问题修复开始，逐步熟悉项目的复杂构建系统。

jupyterlite Wasm powered Jupyter running in the browser 💡 项目地址: https://gitcode.com/gh_mirrors/ju/jupyterlite

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

JupyterLite 项目开发环境搭建与贡献指南