Ctrl+K

贡献#

感谢您对 JupyterLite 的贡献！

我们遵循 Project Jupyter 的行为准则，以营造友好和欢迎的协作环境。

设置#

获取代码#

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

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

先决条件#

您需要

  • git

  • nodejs >=20,<21

  • jupyterlab >=4.0,<4.1

  • python >=3.11,<3.12

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

对于任何平台，推荐的方法是安装 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 到文档构建和链接检查。它理解不同嵌套任务之间的依赖关系，通常作为磁盘上发生更改的文件。

列出任务#

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

doit list --all --status

任务和操作默认值#

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

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

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

注意

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

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 上分发的组件压缩包。参见 #7.

来自

  • 一组 packages 在 @jupyterlite 命名空间中，用 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/latest/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 检查完成

  • 转到工件部分并下载 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 工件下载 Playwright 报告

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

  3. 导航到失败的测试

  4. 滚动到测试的“跟踪”部分，在新的选项卡中打开跟踪

a screenshot showing the Playwright trace

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

（服务器）Python 开发#

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

关于测试#

额外的 PYTEST_ARGS 可以作为（粗俗的）JSON 字符串传递

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

多个任务调用 jupyter lite CLI，该 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 网页界面也会提供。

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

      • 添加像 fixes #123 这样的魔术字符串有助于将协作历史联系在一起。

  • 等待持续集成

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

预览#

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

rtd-pr-preview

工件#

此外，从 Actions 页面上的每次运行中都可以获得多个构建工件，包括

  • 测试报告

  • 可安装的工件

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

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

本页内容
在 GitHub 上编辑
显示源代码