为 Voilà 贡献代码#

Voilà 是 Project Jupyter 的子项目，受 Jupyter 治理和行为准则的约束。

一般指南#

有关为 Jupyter 项目贡献代码的一般文档，请参阅 Project Jupyter 贡献者文档。

社区#

Voilà 团队组织公开视频会议。未来会议的日程安排和过去会议的记录可以在我们的团队指南上找到。

设置开发环境#

首先，您需要 fork 项目。然后设置您的环境。

# create a new conda environment
conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<3" pip
conda activate voila

# download voila from your GitHub fork
git clone https://github.com/<your-github-username>/voila.git

# install JS dependencies and build js assets
cd voila
yarn install

# install Voilà in editable mode
python -m pip install -e .

运行 Voilà#

要启动 Voilà，请运行

voila

或者

python -m voila

这将在 [https://127.0.0.1:8866/](https://127.0.0.1:8866/) 打开一个新的浏览器标签页。

在修改 Voilà 的前端时，打开一个新的终端窗口并运行

cd packages/voila/
npm run watch

然后重新加载浏览器标签页。

注意：notebooks 目录包含一些可以使用 Voilà 运行的示例。查看用户指南中的说明，了解有关如何运行它们的详细信息。

扩展#

服务器扩展#

要手动启用经典笔记本服务器扩展

jupyter serverextension enable voila --sys-prefix

对于 Jupyter Server

jupyter server extension enable voila.server_extension --sys-prefix

这使得 Voilà 可作为服务器扩展使用：https://127.0.0.1:8888/voila/tree。

笔记本扩展#

要安装笔记本扩展

jupyter nbextension install voila --sys-prefix --py
jupyter nbextension enable voila --sys-prefix --py

JupyterLab 扩展#

需要 Node.js，可以使用 conda 安装

conda install -c conda-forge nodejs

JupyterLab 扩展需要启用服务器扩展。可以通过运行以下命令来完成此操作

jupyter serverextension enable voila --sys-prefix

您可以通过运行以下命令来验证服务器扩展是否已启用

jupyter serverextension list

如果您使用 Jupyter Server

jupyter server extension enable voila --sys-prefix

您可以通过运行以下命令来验证服务器扩展是否已启用

jupyter server extension list

JupyterLab 扩展是使用 JupyterLab 3.0 中添加的新分发系统作为预构建扩展开发的。要设置开发环境

# install the package in development mode
python -m pip install -e .

# link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# build the lab extension
jlpm run build --scope @voila-dashboards/jupyterlab-preview

# it is also possible to start in watch mode to pick up changes automatically
jlpm run watch

前端包#

Voilà 存储库包含多个包，例如 Voilà 前端和 JupyterLab 扩展。

它遵循单一存储库结构，并使用 lerna 来简化工作流程。

要一次构建所有前端包，请运行以下命令

# install dependencies
jlpm

# build the packages
jlpm run build

这将在每个包中运行 build 脚本。

使用这种结构，可以轻松地对包进行 linting，并遵循其他 Jupyter 项目中使用的相同代码风格和约定。要对包进行 linting

# install dependencies
jlpm

# run ESLint
jlpm run eslint

# run prettier
jlpm run prettier

关于 Voilà 前端#

Voilà 前端是使用 JupyterLab 组件构建的基于 JupyterLab 的应用程序。

这使得可以重用 Jupyterlab 的现有插件和扩展，例如核心 JupyterLab 插件（如 JSON 查看器），以及第三方 mime 渲染器（如 FASTA 查看器）。

Voilà 前端能够加载已安装为预构建扩展的现有 JupyterLab 扩展，位于 ${PREFIX}/share/labextensions 下，类似于它在 JupyterLab 中的工作方式。

这些扩展通常通过 pip 和 conda 包进行分发，最终用户可以轻松安装，无需 Node.js。小部件包通常现在默认包含一个为 JupyterLab 3.0 预构建的扩展，它应该在 Voila 中自动工作。

查看 JupyterLab 文档关于预构建扩展了解更多信息。

前端代码位于 packages/voila 下，在 packages/voila/index.js 中支持加载联合扩展。

测试#

安装测试依赖项

python -m pip install -e ".[test]"

启用 Jupyter 服务器扩展

jupyter server extension enable voila.server_extension --sys-prefix

在本地运行测试还需要安装 test_template 和 skip_template

python -m pip install ./tests/test_template ./tests/skip_template

最后，要运行测试

python -m pytest

编辑模板#

默认模板文件位于 share/jupyter/voila/templates/default 文件夹中。在开发模式下运行 Voilà 时，它们会自动被拾取。

编辑模板后，重新加载浏览器选项卡以查看更改。