用 Quarto 把 Jupyter 可视化课程发布为多格式书籍:Visualization Curriculum 实战解析

原创2026-10-11 16:17:561,685 阅读
文章标签:开发者工具CLI文档科研数据科学静态站点

用 Quarto 把 Jupyter 可视化课程发布为多格式书籍:Visualization Curriculum 实战解析

导读

本文以 quarto-cli 仓库内置的测试样例 Visualization Curriculum 为核心,解析如何把一套基于 Vega-Lite / Altair 的 Python 交互式笔记本课程,通过 Quarto 书籍(book)工程组织成 HTML、DOCX、AsciiDoc 等多格式出版物的完整流程。读完本文,你将掌握 Quarto book 的目录配置、多格式渲染、ipynb 章节组织,以及 Altair 可视化从 Chart 对象到 Vega-Lite JSON 规范的完整技术链路,并了解仓库中对应的冒烟测试如何验证渲染产物。

从 Jupyter Book 到 Quarto:一本可视化课程的移植

tests/docs/books/visualization-curriculum/ 目录原本是一套面向数据可视化教学的数据可视化课程,包含 Python 版 Jupyter 笔记本(基于 Altair 与 Vega-Lite)以及在线可用的 JavaScript 版本(Observable)。它最初用 Jupyter Book 编写并在互联网发布,后为演示 Quarto 出版系统的用法,将其移植为 Quarto 书籍工程。

从仓库文件清单看,课程源码由以下部分组成:

  • index.md:书籍首页(Introduction),即本任务对应的关联文档;
  • 7 个 .ipynb 章节笔记本(Altair 入门、标记与编码、数据变换、比例尺/坐标轴/图例、视图组合、交互、制图可视化);
  • 1 个支持章节 altair_debugging.ipynb(Altair 调试指南);
  • _quarto.yml:Quarto 书籍工程配置;
  • requirements.txt:Python 环境依赖(Altair 4.x 及 Jupyter 生态);
  • bibliography.bib:参考文献(Knuth 的《Literate Programming》);
  • altair-hist.png:侧边栏 Logo。

这套样例的定位是「可运行的完整书籍工程」,Quarto 开发者可以直接对它执行 quarto render 来产出书籍站点与多格式文档。

Getting Started:在线使用与本地安装

原文档「Getting Started」一节给出三种使用路径,全部继承如下:

  1. 在线阅读 JavaScript 笔记本:在 Observable 上按对应 notebook 阅读;
  2. 在线运行 Python 笔记本:在 Colab 中打开本书对应章节,点击页面顶部的 rocket ship 图标并从菜单选择 Colab;
  3. 本地运行 Python 笔记本:安装 Altair 与笔记本环境(这些笔记本基于 Altair 4),从 releases 页面下载笔记本压缩包,然后在 JupyterLab(v1.0 及以上)中打开。

仓库中的 requirements.txt 完整记录了这套课程在本地复现时需要的环境:核心是 altair==4.1.0,配套 vega-datasets==0.9.0(提供示例数据集)、altair-viewer、altair-saver、altair-data-server(Altair 渲染与输出辅助),以及 jupyterlab==3.0.15、notebook==6.3.0、ipykernel==5.5.5 等笔记本运行栈。离线或特定环境还需要为 Altair 指定 renderer——在 JupyterLab、Jupyter Notebook、Colab 且联网时无需额外配置,否则需参考 Altair 的 display frontends 文档。

_quarto.yml:Quarto Book 工程配置详解

《_quarto.yml》 是这套课程在 Quarto 侧的核心配置,完整内容如下:

project:
  type: book
  output-dir: docs

book:
  title: Visualization Curriculum
  author: Jeffrey Heer, Dominik Moritz, Jake VanderPlas, and Brock Craft
  repo-url: https://github.com/uwdata/visualization-curriculum
  repo-branch: master
  repo-actions: [issue]
  sharing: [twitter, facebook]
  chapters:
    - index.md
    - part: Curriculum
      chapters:
        - altair_introduction.ipynb
        - altair_marks_encoding.ipynb
        - altair_data_transformation.ipynb
        - altair_scales_axes_legends.ipynb
        - altair_view_composition.ipynb
        - altair_interaction.ipynb
        - altair_cartographic.ipynb
    - part: Support
      chapters:
        - altair_debugging.ipynb
  sidebar:
    logo: altair-hist.png

format:
  html:
    theme: cosmo
  asciidoc: default
  docx: default

bibliography: bibliography.bib

逐项说明:

  • project.type: book:声明这是一个书籍工程,Quarto 会启用 book 渲染管线(站点结构、搜索、侧边栏、章节导航等);
  • output-dir: docs:渲染产物输出目录。注意这与一般 book 默认的 _book 不同,正是因为它被设定为 docs,冒烟测试才去该目录检查产物;
  • book.title / author:书籍元信息,作者即 UW 课程的四位开发者;
  • repo-url / repo-branch / repo-actions:在书籍侧边栏/页面上生成指向原仓库的链接与操作按钮(此处配置了 issue 入口);sharing 配置社交分享按钮;
  • book.chapters:章节顺序。index.md 在前,其后用两个 part(Curriculum、Support)分组组织 8 个 ipynb 章节。part 是 Quarto book 里非常实用的能力——它允许把章节分组成带标题的分区,渲染后形成分组导航;
  • sidebar.logo:使用 altair-hist.png 作为侧边栏 Logo;
  • format:多格式输出。HTML 使用 cosmo 主题;同时启用 asciidoc: default 与 docx: default,意味着一次渲染同时产出网页版、AsciiDoc 与 Word 文档三种形态;
  • bibliography:挂载 bibliography.bib,供书籍内引用(例如在 Altair 入门章节中引用 Knuth 1984 的《Literate Programming》)。

这套配置展示了一个关键能力:同一套 ipynb 笔记本源码,不需要为每种格式写任何重复内容,仅通过 format 声明即可同时产出交互式 HTML 与静态 DOCX/AsciiDoc。

渲染多格式书籍:Quarto 命令与测试验证

在仓库中,该书籍工程由冒烟测试 tests/smoke/book/render-book.test.ts 直接驱动验证。测试核心逻辑如下:

const vizInput = docs("books/visualization-curriculum");
const verifyViz = [
  fileExists(join(vizInput, "docs", "Visualization-Curriculum.docx")),
  fileExists(join(vizInput, "docs", "book-asciidoc", "Visualization-Curriculum.adoc")),
  fileExists(join(vizInput, "docs", "index.html")),
];
testQuartoCmd("render", [vizInput], [noErrorsOrWarnings, ...verifyViz], {
  teardown: async () => { /* 删除 docs 输出目录 */ },
});

它印证了以下事实:

  • 对 visualization-curriculum 执行 quarto render 后,产物落在 docs/(对应 output-dir: docs),而非默认 _book/;
  • 由于 _quarto.yml 声明了三种格式,产物包含 docs/index.html(HTML 书籍主页)、docs/Visualization-Curriculum.docx 与 docs/book-asciidoc/Visualization-Curriculum.adoc;
  • 测试还要求渲染过程 noErrorsOrWarnings,即整本书(含 8 个 ipynb 章节)渲染不得出现错误或警告,这保障了该工程始终可作为「可成功渲染的示例」使用;
  • 测试带 teardown,会在验证后清理输出目录,保持仓库干净。

用户可以在本地对该目录执行同样的渲染命令:

quarto render tests/docs/books/visualization-curriculum

渲染结束后即可在 tests/docs/books/visualization-curriculum/docs/ 下查看三种格式的产物。

顺带一提,同目录的 book-404-detection.test.ts 验证了 book 工程对 .ipynb 与 .rmd 两种章节类型的 404 页面生成——即 Quarto 书籍站点会为不存在的路径生成 404.html,并同样产出 search.json 站点搜索索引,说明 book 的静态站点能力覆盖了 ipynb 章节。

章节内容:Altair 入门笔记本的完整技术脉络

虽然关联文档本身是课程首页,但课程的技术主体是 8 个 ipynb 笔记本。以 altair_introduction.ipynb 为例,它构成了「从数据到发布」的完整 Altair 入门路径,是理解全书内容密度的最佳窗口。

数据准备:DataFrame 与 vega-datasets

Altair 数据以 Pandas DataFrame 为核心(数据列即数据字段)。课程首先演示两种取数方式:

import pandas as pd
import altair as alt

from vega_datasets import data   # 导入 vega-datasets
cars = data.cars()               # 直接加载为 Pandas DataFrame
cars.head()

pd.read_json(data.cars.url).head()  # 或通过 URL 加载 JSON

vega-datasets 同时提供内存 DataFrame 与网络 URL 两种形态(data.cars.url 返回一个 JSON 数据地址),后者可被 Altair 直接引用,也可先读入 DataFrame。课程随后构造了一个「整洁数据」(tidy data)示例:city / month / precip 三列的降水数据表,作为后续所有演示的数据基础。

Chart 对象与 Marks/Encoding 模型

Altair 的核心对象是 Chart,以 DataFrame 为唯一参数构造:

chart = alt.Chart(df)

随后用 mark_* 方法指定图形标记,用 encode 方法把数据字段映射到编码通道(x、y、color、shape、size 等):

alt.Chart(df).mark_point()                # 每个数据行一个点,未指定位置时全部重叠
alt.Chart(df).mark_point().encode(y='city')       # 把 city 映射到 y 轴(自动推断为 nominal 类型)
alt.Chart(df).mark_point().encode(x='precip', y='city')  # precip 推断为 quantitative

从笔记本内嵌的 Vega-Lite 规范可以看出,encode(y='city') 实际被展开为 "encoding": {"y": {"type": "nominal", "field": "city"}} 的 JSON。编码定义还有更完整的构造式写法,便于附加参数:

alt.Chart(df).mark_point().encode(
    alt.X('precip'),
    alt.Y('city')
)

两种写法可混用(x='precip', alt.Y('city') 同样合法)。当需要显式指定数据类型时,可用字段名后缀标注:

  • 'b:N':nominal(无序分类)
  • 'b:O':ordinal(有序等级)
  • 'b:Q':quantitative(有意义的数值)
  • 'b:T':temporal(日期/时间)

例如 alt.X('precip:N')。显式标注在直接从 URL 加载数据(绕过 Pandas 类型推断)或希望覆盖推断类型时是必需的。

聚合变换与标记切换

Altair 内置聚合语法,例如 x='average(precip)' 会按 y 轴分组计算平均降水,并在 Vega-Lite 规范中展开为 {"aggregate": "average", "field": "precip", "type": "quantitative"}。支持的聚合函数包括 count、min、max、average、median、stdev 等。换用 mark_bar() 即可把点图改为条形图,交换 x/y 即可在水平与垂直条形图间切换。

自定义可视化

通过通道类的 scale、axis 属性与 mark 的颜色参数定制外观:

alt.Chart(df).mark_point(color='firebrick').encode(
    alt.X('precip', scale=alt.Scale(type='log'), axis=alt.Axis(title='Log-Scaled Values')),
    alt.Y('city', axis=alt.Axis(title='Category')),
)

这里演示了日志比例尺(scale=alt.Scale(type='log'))与自定义轴标题(axis=alt.Axis(title=...)),mark 颜色接受任意合法 CSS 颜色字符串。

多视图组合

单个 Chart 只代表一种标记,复杂图形需要用视图组合算子。入门章节演示了 layer(叠加)算子的 + 简写形式,把汽车数据的年均油耗折线图与各点叠加:

alt.Chart(cars).mark_line().encode(
    alt.X('Year'),
    alt.Y('average(Miles_per_Gallon)')
)

而完整的视图组合代数(layer、facet、concat、repeat 及嵌套组合)由 altair_view_composition.ipynb 系统讲授。后续章节还分别覆盖了:

检查 JSON 输出:理解 Altair 的声明式本质

入门章节专门用一节演示 Chart.to_json(),展示 Altair 如何把 Python 声明翻译为 Vega-Lite 规范:

chart = alt.Chart(df).mark_bar().encode(
    x='average(precip)',
    y='city',
)
print(chart.to_json())

输出为完整的 Vega-Lite JSON——包含 $schema、config、data/datasets、encoding(含 aggregate、field、type)与 mark。同时演示了简写与显式写法的等价性:

x = alt.X('average(precip):Q')
x = alt.X(aggregate='average', field='precip', type='quantitative')

两种写法产出的 JSON 完全一致。这正是「声明式可视化」的含义:用户声明「要什么」(数据、标记、编码通道),细节由 Vega-Lite 自动处理。

发布:Chart.save 与 vega-embed

最后,可视化可直接发布到网页。Chart.save('chart.html') 会生成独立 HTML 文件,模板结构为:在 <head> 中加载 vega、vega-lite、vega-embed 三个 CDN 脚本,在 <body> 中放置挂载点 div#vis,并把 Chart.to_json() 的规范存入 spec 变量后调用 vegaEmbed("#vis", spec, embedOpt) 渲染。该模板在入门章节中以完整代码示例给出,读者可直接复制使用。

目录中的测试与验证体系

该书籍工程不仅是教学样例,还是 Quarto 官方测试矩阵的一部分:

  • render-book.test.ts 用 quarto render 驱动本工程,断言三种格式产物存在且无错误警告;
  • book-404-detection.test.ts 覆盖 .ipynb 与 .rmd 章节的 404 页面与搜索索引生成;
  • 此外 tests/docs/books/ 下还有 simple、book-404-detection、book-404-rmd 等兄弟样例,共同构成 Quarto book 渲染功能的回归测试集。

这意味着:当你在实际项目里使用同样的 _quarto.yml 结构(project.type: book + book.chapters + 多 format),可以得到与这套课程完全一致、经过 CI 验证的渲染行为。

小结

Visualization Curriculum 样例浓缩了 Quarto book 的两个核心价值:内容与格式解耦(一份 ipynb 源码 + 一个 YAML 配置产出 HTML/DOCX/AsciiDoc),以及对 Jupyter 生态的深度支持(8 个交互式笔记本直接作为书籍章节,连同 404 页面、搜索索引等站点能力一并生成)。同时,Altair 入门章节本身也是一份高质量的声明式可视化教程——从 Chart/encode 模型、类型系统、聚合变换到多视图组合与 JSON 导出,覆盖了「从数据到发布」的完整链路。对于希望用 Quarto 组织 Python 数据科学内容的团队,这套工程是可直接复用的模板。

Credits

课程由华盛顿大学的 Jeffrey Heer、Dominik Moritz、Jake VanderPlas 与 Brock Craft 开发,感谢 UW Interactive Data Lab 与 Arvind Satyanarayan 的反馈,也感谢 UW CSE512(2019 春季)首批在整门课程中使用这些笔记本的学生。许可证文件位于 tests/docs/books/visualization-curriculum/LICENSE。

登录后查看全文
quarto-cli