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

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

voila Voilà turns Jupyter notebooks into standalone web applications 项目地址: https://gitcode.com/gh_mirrors/vo/voila

前言

Voilà是一个基于Jupyter生态系统的开源项目，它能够将Jupyter笔记本转换为独立的web应用程序。本文将详细介绍如何搭建Voilà的开发环境，以及如何参与项目开发的技术细节。

开发环境准备

基础环境配置

首先需要创建一个隔离的Python开发环境，推荐使用conda进行管理：

conda create -n voila -c conda-forge notebook jupyterlab nodejs "yarn<4" pip
conda activate voila

这个命令创建了一个名为"voila"的conda环境，并安装了以下关键组件：

• Jupyter Notebook和JupyterLab
• Node.js环境
• Yarn包管理器(版本4以下)
• pip工具

获取源代码

获取项目源代码是开发的第一步：

git clone https://<your-repository>/voila.git
cd voila

前端依赖安装

Voilà项目包含前端组件，需要使用Yarn安装依赖：

yarn install

安装开发模式

为了便于开发，建议以可编辑模式安装Voilà：

python -m pip install -e .

运行与调试

启动Voilà服务

开发过程中可以随时启动Voilà服务：

voila
# 或者
python -m voila

服务默认会监听8866端口。

前端开发实时刷新

当修改前端代码时，可以启动watch模式自动重新构建：

cd packages/voila/
npm run watch

修改代码后只需刷新浏览器即可看到变化。

扩展开发

服务器扩展

Voilà可以作为Jupyter Notebook或Jupyter Server的扩展运行：

对于经典Notebook：

jupyter serverextension enable voila --sys-prefix

对于Jupyter Server：

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

JupyterLab扩展开发

JupyterLab扩展开发需要额外步骤：

1. 首先确保服务器扩展已启用
2. 然后链接开发版本：

jupyter labextension develop . --overwrite

3. 构建扩展：

jlpm run build --scope @voila-dashboards/jupyterlab-preview

4. 或者使用watch模式：

jlpm run watch

项目结构与构建

Voilà采用monorepo结构管理多个前端包，使用lerna工具管理：

• 构建所有前端包：

jlpm run build

• 代码风格检查：

jlpm run eslint  # ESLint检查
jlpm run prettier  # 代码格式化

前端架构解析

Voilà前端基于JupyterLab组件构建，这种设计带来了以下优势：

1. 可以复用JupyterLab现有的插件和扩展
2. 支持加载预构建的扩展
3. 与JupyterLab生态系统保持兼容

前端代码主要位于packages/voila目录下，支持联邦扩展的加载机制。

测试流程

测试准备

安装测试依赖：

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

安装测试模板：

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

运行测试

启用服务器扩展后，运行：

python -m pytest

模板开发

Voilà的默认模板位于share/jupyter/voila/templates/default目录。在开发模式下修改模板后，只需刷新浏览器即可看到变化。

结语

本文详细介绍了Voilà项目的开发环境搭建、代码结构、扩展开发和测试流程。通过遵循这些步骤，开发者可以高效地参与到Voilà项目的开发中。Voilà作为Jupyter生态系统的重要组件，其开发模式也体现了现代web应用的开发理念，值得深入学习和实践。

voila Voilà turns Jupyter notebooks into standalone web applications 项目地址: https://gitcode.com/gh_mirrors/vo/voila