Assemblé

基于Jupyter Lab的芭蕾协作开发环境

使用Assemblé，您可以在Jupyter Lab中开发Ballet项目的补丁，然后一键提交为GitHub Pull Requests（PRs），无需离开您的笔记本。

Assemblé（发音为“assam blay”）是一种芭蕾舞动作，涉及一只脚离地，然后落在两只脚上。

Assemblé由以下部分组成：（1）名为ballet_assemble的Python包，用于服务器扩展；（2）也命名为ballet-assemble的NPM包，用于前端扩展；（3）每个Ballet项目与Binder的紧密集成。

要求

• JupyterLab >= 2.0

安装

可以使用pip完全安装，它会安装服务器和前端扩展。前端扩展只能使用jupyter labextension install安装，但如果没有相应的服务器扩展，则无法正常工作。

pip install ballet_assemble
jupyter lab build

注意：您需要NodeJS来安装扩展；如果找不到，安装过程将报错。

通过GitHub进行认证

该插件为使用 GitHub 进行身份验证提供了实验室体验。当您打开笔记本时，应在笔记本工具栏的右侧看到 GitHub 图标。图标最初应该是灰色，表示您尚未进行身份验证。单击图标打开登录窗口，在窗口中您可以输入您的 GitHub 用户名和密码。这些信息将被插件用于获取 OAuth 令牌，并代表您向上游的 Ballet 项目提出更改（如果您尝试提交功能）。

或者，您可以使用以下配置方法直接提供个人访问令牌。

配置

该插件与 Jupyter [Lab] 本身的配置系统相同。您可以使用命令行参数或配置文件来配置该插件，就像配置 Jupyter Notebook 或 Jupyter Lab 一样。

所有配置选项

以下配置选项可用

$ python -c 'from ballet_assemble.app import print_help;print_help()'

AssembleApp options
-----------------
--AssembleApp.access_token_timeout=<Int>
    Default: 60
    timeout to receive access token from server via polling
--AssembleApp.ballet_yml_path=<Unicode>
    Default: ''
    path to ballet.yml file of Ballet project (if Lab is not run from project
    directory)
--AssembleApp.debug=<Bool>
    Default: False
    enable debug mode (no changes made on GitHub), will read from
    $ASSEMBLE_DEBUG if present
--AssembleApp.github_token=<Unicode>
    Default: ''
    github access token, will read from $GITHUB_TOKEN if present
--AssembleApp.oauth_gateway_url=<Unicode>
    Default: 'https://github-oauth-gateway.herokuapp.com/'
    url to github-oauth-gateway server

命令行参数

使用命令行参数调用 Jupyter Lab，为 ballet 插件提供配置，例如

jupyter lab --AssembleApp.debug=True

配置文件

1. 确定您的 jupyter 配置文件路径（如果不存在，您可能需要创建它）

   touch "$(jupyter --config-dir)/jupyter_notebook_config.py"
   

2. 将所需的配置追加到文件末尾，例如

   c.AssembleApp.debug = True
   

故障排除

如果您看到了前端插件但它没有工作，请检查服务器插件是否启用

jupyter serverextension list

如果服务器插件已安装并启用，但您没有看到前端，请检查前端是否已安装

jupyter labextension list

如果已安装，请尝试

jupyter lab clean
jupyter lab build

贡献

开发安装

jlpm 命令是 JupyterLab 随附的 yarn 版本，它随 JupyterLab 一起安装。您可以使用 yarn 或 npm 替代下面的 jlpm。

# Clone the repo to your local environment
# Move to ballet-assemble directory
# Install server extension
pip install -e .
# Register server extension
jupyter serverextension enable --py ballet_assemble
# Install dependencies
jlpm
# Build Typescript source
jlpm build
# Link your development version of the extension with JupyterLab
jupyter labextension link .

# Rebuild Typescript source after making changes
jlpm build
# Rebuild JupyterLab after making any changes
jupyter lab build

您可以通过监视源目录并在监视模式下运行 JupyterLab 来监视扩展源中的更改，并自动重新构建扩展和应用程序。

# Watch the source directory in another terminal tab
jlpm watch
# Run jupyterlab in watch mode in one terminal tab
jupyter lab --watch

卸载

pip uninstall ballet_assemble
jupyter labextension uninstall ballet-assemble

发布流程

bumpversion <part>
make release

鸣谢

贡献者

• Micah Smith (micahs@mit.edu)