[思源笔记经验分享] Jupyter 模式

简介

主题 Dark+ 在 v1.1.0 大版本更新中来了一个大功能: 在思源中以 Jupyter 的形式执行代码

• 实现方案

  • siyuan-theme-dark-plus/app/jupyter/

• 功能介绍

  • 管理内核与会话

    • 使用 RESTful 风格 API 与 Jupyter 服务进行交互

      • The REST API — Jupyter Server documentation
      • Swagger UI - Jupyter Server API

  • 发送待执行的代码, 接受内核的返回结果并将其插入到笔记中

    • 使用 WebSocket 与 Jupyter 内核进行交互

      • WebSocket kernel wire protocols

如果喜欢该功能, 欢迎为 Dark+ 点一个 ⭐ (*^▽^*)

使用教程

1. 添加 Jupyter 服务对思源的信任

1. 打开配置文件 jupyter_lab_config.py 或 jupyter_notebook_config.py

   • 使用命令 jupyter lab --generate-config 或 jupyter notebook --generate-config 生成配置文件
   • Windows 系统生成的配置文件一般在 C:\Users\<用户名>\.jupyter 目录下

2. 找到 c.ServerApp.allow_origin 或 c.NotebookApp.allow_origin 字段

   • 该字段用于设置被信赖的请求源
   • 也可以通过 c.ServerApp.allow_origin_pat 或 c.NotebookApp.allow_origin_pat 字段使用正则表达式进行设置可信源

3. 将该字段设置为思源 'location.origin' 或 '*'

   • Ctrl + Shift + I 打开思源的开发者工具, 在控制台中输入 location.origin 后回车即可获得思源的源地址, 桌面端一般为 http://127.0.0.1:6806
   • 设置为 '*' 将信任所有请求源
   • 示例: c.ServerApp.allow_origin = 'http://127.0.0.1:6806'

4. 保存文件并启动 jupyter 服务

2. 登录 Jupyter 服务

1. 文档块菜单 > Jupyter > 全局设置

2. 打开全局设置窗口

3. 输入服务器 URL 并点击 确定

   • http(s)://hostname(:port)

4. (可选, Cookie 认证方案) 点击 测试 链接跳转到登录页面并登录

5. (可选, Cookie 认证方案) Ctrl + Shift + I 打开开发者工具, 获得 Cookies

   • 方案 1: 在控制台输入 document.cookie 并从输出结果复制 _xsrf 字段
   • 方案 2: 选择一个网络链接并从 HTTP 请求头的 Cookies 字段复制 _xsrf 字段
   • _xsrf 字段完整格式为 _xsrf=d|xxxxxxxx|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx|dddddddddd
   • d: 一个十进制数字
   • x: 一个十六进制数字

6. 关闭 Jupyter 窗口并重新打开全局设置窗口

7. 输入 Cookies 或 Token 并点击 确定

   • Cookies 认证方案仅适用于 Jupyter 服务与思源服务 URL host 相同的情况

   • 示例:

     • 思源服务 URL: http://127.0.0.1:6806
     • Jupyter 服务 URL: http://127.0.0.1:8888

8. 关闭全局设置窗口

9. 单击 重新加载窗口 按钮或 Ctrl + F5 刷新页面

3. 建立会话

1. 单击 文档块菜单 > Jupyter > 文档设置 菜单项打开文档设置窗口

2. 选择想要启动的内核, 输入 会话名称 与 会话目录, 单击 新建 按钮启动该内核并建立会话

   • 会话名称 是在 Jupyter 中查看活动内核时显示的名称

   • 会话目录 所指定的目录是使用相对路径读写文件时的基点

     • 示例: 假设 Jupyter 服务设置的根目录为 D:\foo\, 这里会话目录设置为 bar\测试, 那么使用该内核访问相对路径 ./ 实际访问的是 D:\foo\bar\ 目录

3. 单击中断或重启按钮, 若没有弹窗则表示成功与服务器建立连接

   • 中断按钮会中断正在运行(忙碌)的内核所执行的任务
   • 重启按钮会重启内核, 内核之前运行时产生的所有变量与数据均会丢失

4. 单击连接按钮

   • 该按钮会将会话与内核信息写入文档块的块属性中
   • 在该文档中想要执行代码时可以使用这些信息建立与内核的连接

5. F5 刷新文档, 若文档右上角内核状态显示 启动中 或 空闲 则表示连接内核成功

4. 运行代码

• 单击代码块菜单 > Jupyter > 运行代码菜单项

  • 单击该项后会以文档关联的内核执行代码块中的代码
  • 之后将代码的执行结果插入到该代码下的超级块中(如果没有则新建)
  • 输出结果中的内容会以 Markdown 源码的形式进行解析

• 代码块菜单 > Jupyter > 运行代码 (转义输出结果)

  • 输出结果中的所有半角符号都使用 \ 进行转义, 从而避免其在插入时解析为 Markdown

5. 关闭连接

• 单击文档块菜单 > Jupyter > 关闭连接菜单项

  • 该操作不会关闭内核与会话, 而是关闭与其的连接

    • 不会清空内核执行代码时产生的变量与数据
    • 下一次运行代码时会重新建立一个 WebSocket 连接

  • 该操作会重置运行序号

6. 关闭内核

1. 单击文档块菜单 > Jupyter > 文档设置打开文档设置窗口
2. 单击 关闭 按钮以关闭会话与内核
3. F5 刷新文档, 若文档右上角内核状态显示 No Kernel 则表示内核关闭成功

注意事项

1. 目前尚未对 input() 输入函数进行适配

2. 目前尚未对除 文本、图片 与 错误输出 以外的返回消息进行适配, 如果需要解析其他消息, 请到 Issues 反馈

   • 反馈时请附代码与样式截图
   • 暂未有对存在鼠标交互操作的 ipywidgets 支持计划

3. 目前尚不支持对 *.ipynb 文件的导入与导出

4. 部分魔术指令可能不支持

使用

• 若不使用 Dark+ 主题, 可以下载该主题 v1.1.0+ 版本, 将 Dark+ 主题目录下的 theme.js 文件 复制 到所使用的其他主题的目录下