Ctrl+K

为Jupyter笔记本投稿#

感谢您对Jupyter Notebook的贡献！

一定要跟上 [Project Jupyter's Code of Conduct] (https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md)提供了一个友好和欢迎的协作环境。

设置开发环境#

注意：您将需要NodeJS来构建扩展包。

这个 jlpm 命令是JupyterLab的固定版本 [yarn] (与JupyterLab一起安装的https://yarnpkg.com/)。您可以使用 yarn 或 npm 代替 jlpm 下面。

Note ：我们建议使用 mamba 以加快环境的创造。

# create a new environment
mamba create -n notebook -c conda-forge python nodejs -y

# activate the environment
mamba activate notebook

# Install package in development mode
pip install -e ".[dev,test]"

# Link the notebook extension and @jupyter-notebook schemas
jlpm develop

# Enable the server extension
jupyter server extension enable notebook

notebook 遵循单一回购结构。要一次构建所有程序包，请执行以下操作：

jlpm build

也有一个 watch 用于监视更改并自动重建应用程序的脚本：

jlpm watch

以确保 notebook 已安装服务器扩展：

$ jupyter server extension list
Config dir: /home/username/.jupyter

Config dir: /home/username/miniforge3/envs/notebook/etc/jupyter
    jupyterlab enabled
    - Validating jupyterlab...
      jupyterlab 3.0.0 OK
    notebook enabled
    - Validating notebook...
      notebook 7.0.0a0 OK

Config dir: /usr/local/etc/jupyter

然后用以下命令启动Jupyter Notebook：

jupyter notebook

笔记本相关性中的本地更改#

上面描述的开发安装从 [npmjs] (https://www.npmjs.com/)，根据 package.json 文件。但是，有时能够测试Notebook中的更改以及依赖项(例如， @jupyterlab 包)，尚未发布。

[yalc] (https://github.com/wclr/yalc)可以帮助您在构建的Notebook中使用本地的JAVASCRIPT包，充当本地包库。

  • 在您的环境中全局安装yalc： npm install -g yalc

  • 发布您的依赖项包：\ yalc publish ，从程序包根目录。\例如，如果您在上进行开发 @jupyterlab/ui-components, 此命令必须从执行 path_to_jupyterlab/packages/ui-components.

  • 依赖笔记本中的此本地存储库：

    • 从笔记本根目录：\ yalc add your_package ：这将创建一个 dependencies 在主要条目中 package.json 文件。\在前面的示例中，它将是 yalc add @jupyterlab/ui-components 。

    • Notebook是一个monerepo，因此我们希望将此依赖项作为解析(针对所有子程序包)而不是依赖项进行链接。\最简单的方法是手动将新条目移入 package.json 从… dependencies 至 resolutions.

    • 使用本地依赖项生成笔记本：\ jlpm install && jlpm build

然后，必须使用以下命令构建和推送依赖项中的更改 jlpm build && yalc push (从程序包根目录)，并使用以下命令从笔记本中获取 yarn install 。

Warning ：您需要确保Notebook和本地包的依赖项正确匹配，否则在构建过程中webpack会出现错误。\在上例中，两者都 @jupyterlab/ui-components 和笔记本电脑依赖于 @jupyterlab/coreutils. 我们强烈建议您使用相同的版本。

运行测试#

要运行测试，请执行以下操作：

jlpm run build:test
jlpm run test

还有端到端测试，以涵盖更高级别的用户交互，位于 ui-tests 文件夹。要运行这些测试，请执行以下操作：

cd ui-tests
#install required packages for jlpm
jlpm

#install playwright
jlpm playwright install

# start a new Jupyter server in a terminal
jlpm start

# in a new terminal, run the tests
jlpm test

这个 test 脚本调用剧作家测试跑步者。您可以将其他参数传递给 playwright 通过将参数附加到命令。例如在引导模式下运行测试， jlpm test --headed 。

请查看 [Playwright Command Line Reference] (https://playwright.dev/docs/test-cli/)了解有关可用命令行选项的详细信息。

在Headful模式下运行端到端测试将触发如下内容：

好了！ [playwight-headed-demo] (https://user-images.githubusercontent.com/591645/141274633-ca9f9c2f-eef6-430e-9228-a35827f8133d.gif)

任务缓存#

存储库配置为使用Lerna缓存系统(通过 nx )用于某些开发脚本。

这有助于在运行时加快重建速度 jlpm run build 以避免重新生成磁盘上未更改的包。

您可以使用以下命令生成图表，以便更好地了解所有包之间的依赖关系：

npx nx graph

默认情况下，运行该命令将打开浏览器选项卡，其中包含如下所示的图形：

好了！ [a screenshot showing the nx task graph] (https://github.com/jupyter/notebook/assets/591645/34eb46f0-b0e5-44b6-9430-ae5fbd673a4b)

要了解有关Lerna缓存的更多信息：

  • https://lerna.js.org/docs/features/cache-tasks

  • https://nx.dev/features/cache-task-results

更新参考快照#

通常，PR可能会对用户界面进行更改，这可能会导致视觉回归测试失败。

如果你想在处理公关时更新参考快照，你可以把下面这句话作为GitHub的评论发布：

bot please update playwright snapshots

这将触发GitHub操作，该操作将自动运行UI测试，并在引用快照发生更改时将新提交推送到分支。

代码样式设置#

所有非Python源代码的格式都使用 [prettier] (https://prettier.io)和PYTHON源代码的格式为 [black] (https://github.com/psf/black)s在修改和提交代码时，将使用预先提交的GIT挂钩自动格式化所有暂存文件(在 [pre-commit] (https://github.com/pre-commit/pre-commit).)使用代码格式化程序的好处，如 prettier 和 black 在审查Pull请求时，它从对话中删除了代码风格的主题，从而加快了审查过程。

只要您的代码有效，预提交挂钩就应该注意它的外观。 pre-commit 运行时，将自动安装与其关联的挂钩 pip install -e ".[dev,test]"

要安装 pre-commit 手动运行以下命令：

pip install pre-commit
pre-commit install

您可以通过以下方式随时手动调用预提交挂接：

pre-commit run

它应该对你的代码运行任何自动格式化，并告诉你任何它不能自动修复的错误。您还可以安装 [black integration] (https://github.com/psf/black#editor-integration)到您的文本编辑器中，以自动格式化代码。

如果您在使用设置预提交挂接之前已经提交了文件 pre-commit install ，您可以使用以下命令修复所有问题 pre-commit run --all-files 。在那之后，你需要让修复你自己承诺。

您也可以使用更漂亮的NPM脚本(例如 npm run prettier 或 yarn prettier 或 jlpm prettier )格式化整个代码库。我们建议您为代码编辑器安装一个更漂亮的扩展，并将其配置为使用键盘快捷键或在保存时自动格式化代码。

默认情况下，某些挂钩仅在配置项上运行，但您可以通过使用 --hook-stage manual 争论。

文档#

首先，确保您已经设置了如上所述的开发环境。

然后运行以下命令来构建文档：

hatch run docs:build

在单独的终端窗口中，运行以下命令以提供文档：

hatch run docs:serve

现在打开Web浏览器并导航到 http://localhost:8000 以访问文档。

从浏览器进行贡献#

或者，您也可以在不设置本地环境的情况下，直接从Web浏览器向Jupyter Notebook投稿：

  • [Gitpod] 已启用(https://gitpod.io/#https://github.com/jupyter/notebook)集成。Gitpod配置会自动构建Jupyter Notebook应用程序和文档。

  • GitHub的 [built-in editor] (https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)适用于提供小的修复

  • 更高级的 [github.dev] 按圆点(.)可访问(https://docs.github.com/en/codespaces/the-githubdev-web-based-editor)编辑器。密钥，而在Jupyter Notebook GitHub存储库中，

On this page
Edit on GitHub