用 Quarto 把 Jupyter 可视化课程发布为多格式书籍:Visualization Curriculum 实战解析
用 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」一节给出三种使用路径,全部继承如下:
- 在线阅读 JavaScript 笔记本:在 Observable 上按对应 notebook 阅读;
- 在线运行 Python 笔记本:在 Colab 中打开本书对应章节,点击页面顶部的 rocket ship 图标并从菜单选择 Colab;
- 本地运行 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 系统讲授。后续章节还分别覆盖了:
- altair_marks_encoding.ipynb:数据类型的完整讨论与编码通道、图形标记;
- altair_scales_axes_legends.ipynb:比例尺、坐标轴、颜色图例的配置;
- altair_data_transformation.ipynb:直方图、聚合、高级数据变换;
- altair_interaction.ipynb:选择(selections)、动态查询、平移缩放、概览+细节导航、按需细节、刷选联动;
- altair_cartographic.ipynb:GeoJSON/TopoJSON、geoshape、点图、符号地图、等值区域图(choropleth)与地图投影;
- altair_debugging.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。