贡献#

感谢您为 JupyterLite 做出贡献！

我们遵循Project Jupyter 的行为准则，以营造一个友好和热情的协作环境。

设置#

获取代码#

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

如果您还没有 git，您可以使用下面的说明来获取它

先决条件#

您需要

  • git

  • nodejs >=20,<21

  • jupyterlab >=4.4.5,<4.5

  • python >=3.12,<3.13

不同操作系统上的各种包管理器都提供了这些。

对于任何平台，推荐的方法是安装Mambaforge，并使用仓库中签入的 Binder 环境描述。

mamba env update --file .binder/environment.yml
mamba activate jupyterlite-dev

要获得完整的归档重现性测试输出（仅在 Linux 上可用），还需要运行

mamba install -c conda-forge diffoscope

为了提高 GitHub Actions 的速度，python 和 nodejs 是直接安装的。如果您已经安装了这些，要安装完整的开发堆栈

python -m pip install -r requirements-docs.txt -r requirements-lint.txt

开发任务#

doit#

doit 处理完整的软件生命周期，从 JavaScript 到文档构建和链接检查。它理解不同嵌套任务之间的依赖关系，通常表现为磁盘上更改的文件。

设置开发安装#

要设置开发安装，只需运行

doit dev

列出任务#

要查看所有可用任务，请使用 list 操作

doit list --all --status

任务和操作默认值#

doit 的默认操作是 run，它……运行指定的任务。

默认任务是 build 和 docs:app:build，因此以下是等效的

doit
doit build docs:app:build
doit run build docs:app:build

注意

作为参考，默认的 doit 任务定义在 dodo.py 文件中的 DOIT_CONFIG 变量中。

doit serve#

可以启动一些开发服务器，用于交互式本地开发和文档编写。

这些提供不同的资产和工具，并遵循不同的环境变量

  • 5000：来自 ./app 的核心资产

    • doit serve:core:js

    • doit serve:core:py

  • 8000：示例站点 ./build/docs-app 在

    • doit serve:docs:app

      • LITE_ARGS（一个 JSON 字符串列表）控制 jupyter lite 的 CLI 参数

  • 8888：JupyterLab

    • doit serve:lab

      • LAB_ARGS（一个 JSON 字符串列表）控制 jupyter lab 的 CLI 参数

核心 JavaScript 开发#

JupyterLite 核心 JS 开发工作流构建

  • 每个 notebook、lab 和 repl 前端的多个应用程序

    • 每个应用程序的入口点位于 {appName}/index.html 下。例如

      • lab/index.html：打开 JupyterLab 界面

      • notebooks/index.html?path=example.ipynb：打开带 example.ipynb 笔记本的笔记本界面

      • tree/index.html：通过 Jupyter Notebook 界面打开文件浏览器

    • 通用配置工具

  • typedoc 文档

  • 待定：一组在 npmjs.com 上分发的组件 tarball。请参阅 #7。

来自

  • @jupyterlite 命名空间中的一组 packages，用 TypeScript 编写

  • 一些 buildutils

  • 一些 webpack 配置

  • 一些未编译的、原生的 JS，用于非常早期的加载工具

    • 待办：修复此问题，可能使用 jsdoc 标签

虽然下面大多数脚本都将由 doit 运行（根据更改以正确的顺序），但以下脚本（在 package.json 中定义）值得强调。

快速入门#

大多数开发任务可以通过一个命令运行

jlpm bootstrap

安装 JavaScript 依赖项#

jlpm

构建应用#

构建开发资产

jlpm build

构建生产资产

jlpm build:prod

提供应用#

这些**不是真正的服务器解决方案**，但它们将为 JupyterLite 的开发、测试和演示目的正确提供所有资产类型（包括 .wasm）。

要使用基于 Node.js http 模块的 scripts/serve.js 提供服务

jlpm serve

要使用 Python 内置的 http.server 模块提供服务（需要 Python 3.7+）

jlpm serve:py

监视源文件#

jlpm watch

代码检查/格式化源文件#

jlpm lint

运行单元测试#

jlpm build:test
jlpm test

安装其他内核#

默认情况下，此存储库只包含 JavaScript 内核。

如果您想设置一个包含额外内核的本地环境，您可以在运行 jupyter lite build 命令之前明确安装。例如

  • 安装 Pyodide 内核：pip install jupyterlite-pyodide-kernel

  • 安装 Xeus Python 内核：https://jupyterlite-xeus.readthedocs.io/en/stable/environment.html

UI 测试#

jupyterlite 使用 Galata 框架进行端到端和视觉回归测试。Galata 构建在 Playwright 之上，提供了一个高级 API 来以编程方式与 JupyterLab UI 交互，以及用于截屏和生成测试报告的工具。

本地运行 UI 测试#

首先安装依赖项

cd ui-tests
jlpm install

UI 测试使用自定义 JupyterLite 网站

# in ui-tests directory

# build
jlpm build

然后运行 test 脚本

# in the ui-tests directory
jlpm test

您可以通过在命令后附加参数来将额外参数传递给 playwright。例如，要在有头模式下运行测试，jlpm test --headed。

有关可用命令行选项的更多信息，请查阅 Playwright 命令行参考。

添加新的 UI 测试#

新的测试套件可以添加到 ui-tests/tests 目录。您可以在 JupyterLab 仓库中看到一些额外的示例测试套件。如果新套件中的测试正在进行视觉回归测试或 HTML 源回归测试，那么您还需要将其参考图像添加到 -snapshots 目录中。

参考图像捕获#

添加新的视觉回归测试时，首先确保您的测试在您的开发环境中本地通过，并在您的开发环境中生成参考快照。您可以通过运行以下命令生成新的参考快照

jlpm test:update

更新快照

  • 将新更改推送到分支

  • 等待 CI 检查完成

  • 前往 artifacts 部分，下载 jupyterlite-chromium-updated-snapshots 和 jupyterlite-firefox-updated-snapshots 存档

  • 解压存档

  • 复制 -snapshots 目录以替换现有目录

  • 提交并推送更改

或者，您也可以在 PR 上发表评论，内容如下

bot please update playwright snapshots

机器人应该通过留下一个👍表情符号来响应评论，并在后台 GitHub Action 运行中触发快照更新。

生成的快照可以在 CI 检查的摘要页面上找到

reference-snapshots

UI 测试故障排除#

UI 测试启用了 Playwright trace 选项，这有助于更深入地查看 CI 上失败的测试，包括控制台错误和网络调用。

查看追踪

  1. 从 GitHub Actions artifacts 下载 Playwright 报告

  2. 启动一个网络服务器（例如使用 python -m http.server），并在浏览器中打开报告

  3. 导航到失败的测试

  4. 滚动到测试的“Trace”部分以在新标签页中打开追踪

a screenshot showing the Playwright trace

更多信息：https://playwright.net.cn/docs/trace-viewer

（服务器端）Python 开发#

在所有 jlpm 相关工作完成后，终端兼容的 python 使用 app 的 npm 兼容 tarball 来构建结合了**原始用户内容**的新站点。

关于测试#

可以通过（粗略的）JSON 字符串传递额外的 PYTEST_ARGS

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

一些任务调用 jupyter lite CLI，其在主文档站点中有进一步描述。

文档#

文档站点，位于 jupyterlite.rtfd.io，使用了软件生命周期不同部分的信息（例如，包含已构建的 app 目录的存档），因此推荐使用 doit 工具。

此外，一些文档是用可执行的 .ipynb 编写的，由 myst 转换：建议使用 doit serve:lab 来编辑这些文档。

构建文档#

doit docs

额外的 sphinx-build 参数由 SPHINX_ARGS 环境变量设置。例如，在所有警告上失败（ReadTheDocs 构建的配置）

SPHINX_ARGS='["-W"]' doit docs

监视文档#

doit watch:docs

这也遵循 SPHINX_ARGS 变量。如果在主题层上工作，建议使用 SPHINX_ARGS='["-a", "-j8"]'，因为默认情况下静态资产不包含在需要更新的计算中。

社区任务#

问题#

JupyterLite 的功能和错误修复首先在 GitHub 上作为问题提出。

  • 浏览现有问题（和拉取请求！）以查看是否存在相关问题或正在处理的问题

  • 如果是新问题

    • 发起一个新问题

    • 选择合适的模板

    • 填写模板

    • 等待社区响应

拉取请求#

JupyterLite 的功能和修复通过拉取请求变为现实。

拉取请求是讨论进行中工作的好地方，但**强烈建议**在开始工作之前创建问题，以便社区可以权衡选择。

  • 派生仓库

  • 从 main 创建一个新分支

  • 进行更改

  • 运行 doit

  • 推送到您的派生

  • 发起拉取请求

    • 您的 git CLI 应该会为您提供一个链接，GitHub Web UI 也会如此

    • 引用一个或多个问题，以便感兴趣的人可以找到您的工作

      • 添加诸如 fixes #123 之类的魔术字符串有助于将协作历史联系起来

  • 等待持续集成

    • 如果出现问题，请修复或寻求帮助！

预览#

每个拉取请求都在 ReadTheDocs 上构建和部署。您可以通过点击 ReadTheDocs 检查查看实时预览站点

rtd-pr-preview

工件#

此外，Actions 页面上的每次运行都提供了几个构建工件，包括

  • 测试报告

  • 可安装工件

  • 一个准备好用作 jupyter lite CLI 输入的应用程序存档，其中包含所有演示内容和支持扩展。

您必须登录 GitHub 才能下载这些文件。