企业官网建设流程全解析

Matplotlib Cheatsheets 是 Matplotlib 官方维护的速查资源仓库，docs/index.rst是 Sphinx 文档站点的首页，以网格形式集中呈现了全部交付物：双页 Cheatsheets 速查表（PDF）、面向初学/进阶/技巧三阶段的 Handouts 讲义（PDF），并引导用户以 Issue、建议或 Pull Request 方式参与贡献。本文将以该首页为骨架，结合仓库内 cheatsheets.tex、三份 handout-*.tex 源文件与顶层 Makefile 构建脚本，完整还原这套速查资源的内容构成、源码实现与从零编译流程，使读者既能按图索骥地使用速查表，也能作为贡献者复现整套文档构建。

文档首页的结构：一份「入口即目录」的 Sphinx 页面

docs/index.rst是整个文档站点的根页面，全文可以拆解为三个语义块，对应三类读者诉求：

• Cheatsheets 区块：使用sphinx_design提供的.. grid:: 2双列网格，各放置一张 270px 宽的cheatsheets-1.png/cheatsheets-2.png预览图（对应速查表 PDF 的两页），并给出cheatsheets.pdf下载链接；
• Handouts 区块：使用.. grid:: 1 2 3 3四列网格，依次展示handout-beginner.png、handout-intermediate.png、handout-tips.png三张预览图及其 PDF 下载链接；
• Contribute 区块：明确说明 Issues、建议或 Pull Request 均被仓库接受，欢迎社区直接向matplotlib/cheatsheets提交。

注意，预览 PNG 与 PDF 均为构建产物而非源码：它们由顶层 Makefile 的convert（ImageMagick）从 XeLaTeX 编译出的 PDF 转制，并在docs目标中通过cp ./cheatsheets*.p* ./docs/_build/html、cp ./handout-*.p* ./docs/_build/html拷贝进 Sphinx 的_build/html输出目录（见 Makefile 第 53-56 行）。因此该首页的图片与链接共同指向的是一套「LaTeX 源文件 → PDF → PNG」的生成链路。

docs/index.rst本身还依赖docs/conf.py中声明的sphinx_design扩展（见 docs/conf.py 第 17 行），主题使用mpl_sphinx_theme，并为 HTML 输出引入了css/normalize.css与css/landing.css两个自定义样式表。也就是说，这个首页的网格布局能力来自 Sphinx 生态，而非 RST 原生语法。

Cheatsheets：一张纸浓缩 Matplotlib 核心 API

速查表对应的 LaTeX 源文件是 cheatsheets.tex，采用10pt, landscape, a4paper的横版 A4 版面，页边距压缩到 2.5mm，正文以\scriptsize排印，并分成 5 栏（multicols*{5}）以容纳海量信息。速查表共两页，其内容模块几乎覆盖了 Matplotlib 日常绘图的全部高频知识点：

1. Quick start 与 Figure anatomy

开篇即给出最简可运行示例：import numpy as np、import matplotlib as mpl、import matplotlib.pyplot as plt，随后用np.linspace(0, 2*np.pi, 100)构造数据、fig, ax = plt.subplots()创建画布与坐标轴、ax.plot(X, Y, color='green')绘制、fig.savefig("figure.pdf")保存并plt.show()展示——这是一套完整的「初始化 → 绘图 → 输出」工作流模板。

紧接着是 Anatomy of a figure 图示（由 scripts/anatomy.py 生成figures/anatomy.pdf），系统标注了 Figure、Axes、Spines、Title、X/Y axis label、Major/Minor tick 及其 label、Grid、Legend、Line（line plot）、Markers（scatter plot）等图形元素。该脚本的坐标轴配置极具教学价值：

• MultipleLocator(1.000)控制主刻度间距，AutoMinorLocator(4)自动放置 4 个次刻度；
• FuncFormatter(minor_tick)对次刻度格式化，仅显示小数部分（如0.25、0.75），整刻度返回空串；
• ax.tick_params(which='major'|'minor', width=…, length=…, labelsize=…)分别定制主/次刻度外观；
• 通过path_effects=[withStroke(linewidth=5, foreground='w')]为标注圆环添加白色描边，保证文字可读性。

2. 布局与子图（Subplots layout）

速查表给出四种坐标轴布局手段及其关键参数：

• subplots：如fig, axs = plt.subplots(3, 3)批量创建子图网格；
• gridspec(rows, cols, …)：通过ax = G[0, :]实现跨行/跨列的不规则切片布局；
• ax.inset_axes(extent)：在坐标轴内嵌局部放大图；
• make_axes_locatable(ax)：配合ax = d.new_horizontal('10%')为坐标轴腾出横向附属区域（常用于放置 colorbar）。

3. Basic plots 与 Advanced plots 参数矩阵

速查表以「函数签名 + 关键参数」表格形式总结了 12 种基础图与 8 种进阶图：

其中参数标记用「加粗 = 必填、灰色 = 可选」区分（\optional与\mandatory宏，见 cheatsheets.tex 第 152-156 行），并在 PDF 中使用\pdftooltip嵌入悬停提示。例如fmt参数的工具提示解释了'ro'即红色圆点格式串，interpolation参数列出'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos'全部取值；Z参数则区分了 (M,N) 标量数据、(M,N,3) RGB（0-1 浮点或 0-255 整数）与 (M,N,4) RGBA 三种输入形态；cmap参数完整列出 Uniform、Sequential、Diverging、Cyclic、Qualitative 五大类共 40 余个内置 colormap 名称。

4. Scales、Projections 与线型/标记/颜色

• 坐标轴刻度类型：ax.set_[xy]scale(scale, …)支持linear（任意值）、log（要求值 > 0）、symlog（任意值）、logit（要求 0 < 值 < 1）四种；
• 投影：subplot(…, projection=p)支持p='polar'、p='3d'，并可结合 Cartopy 使用p=ccrs.Orthographic()等地图投影；
• 线条与标记：以整幅linestyles.pdf/markers.pdf图示展示线型与标记全集；
• 颜色体系：速查表给出 6 种颜色书写方式——'Cn'（默认色环索引，如C0）、'x'（单字符颜色）、'name'（命名颜色）、(R,G,B[,A])（RGB/RGBA 元组）、'#RRGGBB[AA]'（十六进制）、'x.y'（灰度值）。

5. Colormaps 大全与 Tick 控制

第二页集中展示五大类 colormap 的色带预览：Uniform（viridis,plasma,inferno,magma,cividis）、Sequential（Greys至YlGn共 18 个）、Diverging（PiYG至seismic共 12 个）、Qualitative（Pastel1至tab20c共 12 个）以及 Miscellaneous（terrain,ocean,cubehelix,rainbow,twilight）。

Tick 部分则给出两条核心调用链：

from matplotlib import ticker ax.[xy]axis.set_[minor|major]_locator(locator) # 例如 MultipleLocator(0.2) ax.[xy]axis.set_[minor|major]_formatter(formatter)

6. Ornaments：legend / colorbar / annotate

• ax.legend(…)：参数包括 handles、labels、loc、title、frameon；
• ax.colorbar(…)：参数包括 mappable、ax、cax、orientation；
• ax.annotate(…)：必填text、xy、xytext，可选xycoords、textcoords、arrowprops。

Legend 放置一栏还给出了完整的 loc 编号表：2 左上、9 上中、1 右上、6 左中、10 居中、7 右中、3 左下、8 下中、4 右下，以及配合bbox_to_anchor=(x, y)的 A–L 十二种图外定位组合（如 A: upper right /(-0.1, 0.9)、D: upper left /(0.1, -0.1)、K: lower center /(0.5, 1.1)）。

7. 交互、动画与样式

• 事件处理：fig.canvas.mpl_connect('button_press_event', on_click)绑定回调；
• 动画：FuncAnimation(plt.gcf(), animate, interval=5)，回调中line.set_ydata(np.sin(T+i/50))更新数据；
• 样式：plt.style.use(style)，速查表实测展示default、classic、grayscale、ggplot、seaborn-v0_8、fast、bmh、Solarize_Light2、seaborn-v0_8-notebook九种内置样式对比图。

8. Quick reminder、How do I… 与性能提示

「Quick reminder」速查块列出高频 API：ax.grid()、ax.set_[xy]lim(vmin, vmax)、ax.set_[xy]label(label)、ax.set_[xy]ticks(ticks, [labels])、ax.set_title(title)、ax.tick_params(width=10, …)、fig.suptitle(title)、fig.tight_layout()、plt.gcf()/plt.gca()、mpl.rc('axes', linewidth=1, …)、fig.patch.set_alpha(0)，以及 Matplotlib 的 mathtext 语法r'$\frac{-e^{i\pi}}{2^n}$'。

「How do I …」问答块覆盖 20 余个高频诉求，例如：

• 调整图形尺寸：fig.set_size_inches(w, h)
• 保存透明图形：fig.savefig("figure.pdf", transparent=True)
• 清除画布/坐标轴：fig.clear()/ax.clear()；关闭所有图形：plt.close("all")
• 移除刻度/刻度标签：ax.set_[xy]ticks([])/ax.set_[xy]ticklabels([])
• 旋转刻度标签：ax.tick_params(axis="x", rotation=90)
• 隐藏顶轴脊线：ax.spines['top'].set_visible(False)；隐藏图例边框：ax.legend(frameon=False)
• 误差带：ax.fill_between(X, Y+error, Y-error)
• 矩形补丁：ax.add_patch(plt.Rectangle((0, 0), 1, 1))；竖线：ax.axvline(x=0.5)
• 透明效果：ax.plot(…, alpha=0.25)
• 反转/离散 colormap：plt.get_cmap("viridis_r")/plt.get_cmap("viridis", 10)
• 短暂显示图形：fig.show(block=False)+time.sleep(1)

「Performance tips」块则给出三组「慢 vs 快」对照：scatter(X, Y)（慢）优于plot(X, Y, marker="o", ls="")（快）；循环逐点plot(i, X[i], "o")（慢）优于一次plot(X, marker="o", ls="")（快）；cla(); imshow(…); canvas.draw()（慢）优于im.set_data(…); canvas.draw()（快）。

速查表末尾还附有交互快捷键表（Ctrl+S保存、Ctrl+W关闭、r重置视图、f全屏、b/f回退/前进视图、p平移、o框选缩放、x/y单轴平移缩放、g/G次/主网格开关、l/LX/Y 轴对数线性切换）以及 Rougier 提出的「Ten simple rules for better figures」（了解受众、明确信息、适配图形、图注不可省略、不要轻信默认值、有效使用颜色、不误导读者、避免图表垃圾、信息胜过美观、选对工具）。

Handouts：面向三阶段用户的精编讲义

首页 Handouts 区块对应三份独立 LaTeX 文件，每份均为横版 A4、三栏排版、一页篇幅，并在页脚注明「Matplotlib 3.10.8 handout」、CC-BY 4.0 许可与 NumFOCUS 支持。它们分别面向初学者、进阶用户与技巧爱好者：

Beginner：四步上手 + 选择 / 微调 / 组织 / 标注 / 探索 / 保存

handout-beginner.tex 用编号框给出了最朴素的工作流：

# 1 Initialize import numpy as np import matplotlib.pyplot as plt # 2 Prepare X = np.linspace(0, 10*np.pi, 1000) Y = np.sin(X) # 3 Render fig, ax = plt.subplots() ax.plot(X, Y) plt.show() # 4 Observe

「Choose」小节给出 8 种图的最小示例：ax.scatter(X, Y)、ax.bar(X, Y)、ax.imshow(Z)、ax.contourf(Z)、ax.pie(Z)、ax.hist(Z)、ax.errorbar(X, Y, Y/4)、ax.boxplot(Z)。「Tweak」小节展示color="black"、linestyle="--"、linewidth=5、marker="o"四种最常用样式参数。「Organize」小节演示ax.plot(X, Y1, X, Y2)同轴多曲线、plt.subplots(2, 1)上下分栏、plt.subplots(1, 2)左右分栏。「Label」小节演示fig.suptitle(None)、ax.set_title("A Sine wave")、ax.set_xlabel("Time")。「Save」小节强调位图与矢量双格式保存：fig.savefig("my-first-figure.png", dpi=300)与fig.savefig("my-first-figure.pdf")。

Intermediate：解剖图形层级与进阶控制

handout-intermediate.tex 开篇即点明「一张 Matplotlib 图形由层级化元素构成，且每一层都可修改」，随后以anatomy.pdf图示展开：

• Figure / Axes / Spines：plt.subplots(3, 3)配合axs[0, 0].set_facecolor("#ddddff")逐个着色；fig.add_gridspec(3, 3)+fig.add_subplot(gs[0, :])创建跨列坐标轴；ax.spines["top"].set_color("None")隐藏脊线；
• Ticks & labels：MultipleLocator(0.2)设置次刻度间距、ScalarFormatter()格式化次刻度、ax.tick_params(axis='x', which='minor', rotation=90)旋转次刻度标签；
• Lines & markers：ax.plot(X, Y, "C1o:", markevery=50, mec="1.0")—— 一个参数串同时指定颜色C1、标记o、虚线:，并借助markevery稀疏标记、mec设置标记边缘色；
• Scales & projections：ax.set_xscale("log")对数坐标；
• Text & ornaments：ax.fill_betweenx([-1, 1], [0], [2*np.pi])绘制区间背景，ax.text(0, -1, r" Period $\Phi$")插入含 mathtext 的标注；
• Legend：ax.legend(bbox_to_anchor=(0,1,1,.1), ncol=2, mode="expand", loc="lower left")实现跨轴宽度的双列图例；
• Annotation：ax.annotate("A", (X[250],Y[250]), (X[250],-1), ha="center", va="center", arrowprops={"arrowstyle": "->", "color": "C1"})；
• Size & DPI：附有一则「两栏 A4 论文插图尺寸推算」的实用示例——页宽 21cm、两侧各 2cm 边距、栏间距 1cm 时，单栏宽度(21 - 2*2 - 1)/2 = 8cm，按 2.54cm/英寸换算得figsize=(3.15, 3.15)；再配合fig = plt.figure(figsize=(3.15, 3.15), dpi=50)与plt.savefig("figure.pdf", dpi=600)实现低内存预览、高分辨率输出。

Tips：12 个让图形更专业的技巧

handout-tips.tex 汇集了日常出图中最实用的技巧：

• 透明度（Transparency）：多层ax.scatter(X, Y, 40, "C1", lw=0, alpha=0.1)叠加，用半透明展示点密度、刻画数据前沿；
• 栅格化（Rasterization）：对包含 10_000 点的大散点图ax.scatter(X, Y, rasterized=True)栅格化以省内存，其余矢量元素保持不变，输出时fig.savefig("rasterized-figure.pdf", dpi=600)；
• 离线渲染（Offline rendering）：通过 Agg 后端FigureCanvas(Figure())+canvas.draw()+np.array(canvas.renderer.buffer_rgba())直接渲染到内存数组；
• 连续色取值：cmap = plt.get_cmap("Oranges")后以cmap([0.2, 0.4, 0.6, 0.8])在色带上采样，喂给ax.hist(X, 2, histtype='bar', color=colors)；
• 文字描边：matplotlib.patheffects的fx.Stroke(linewidth=3, foreground='1.0')与fx.Normal()组合提升文字可读性；
• 多线段一图：用None作为分隔符把多条折线合并进单次ax.plot(X, Y, "black")；
• 圆点虚线：linestyle=(0, (0.01, 1))配合dash_capstyle="round"得到圆头点线；
• 叠加双投影坐标轴：fig.add_axes([0, 0, 1, 1], label="cartesian")与fig.add_axes([0, 0, 1, 1], label="polar", projection="polar")叠加笛卡尔与极坐标视图；
• Colorbar 尺寸控制：plt.colorbar(im, fraction=0.046, pad=0.04)微调色条占比与间距，cb.set_ticks([])移除刻度；
• 排版瘦身：循环ax.get_xticklabels(which='both')并tick.set_fontname("Roboto Condensed")，用窄体字体压缩刻度标签宽度；
• 去除边距：tight_layout()收拢白边，残余边距可用 TeX Live 附带的pdfcrop工具裁剪；
• 粗线条填充纹：plt.rcParams['hatch.color'] = cmap(0.2)、plt.rcParams['hatch.linewidth'] = 8配合ax.bar(X, Y, color=cmap(0.6), hatch="/")获得醒目填充纹理。

从零构建：字体、图形、PDF 与站点的一体化流程

docs/index.rst展示的 PDF 与 PNG 均产自一条完整链路，顶层 Makefile 用all: figures cheatsheets handouts docs串起全部产物：

1. 准备字体：make -C fonts（即 fonts/Makefile）通过wget下载 Roboto、Roboto Mono、Roboto Slab、Source Code Pro、Source Sans Pro、Source Serif Pro 与 Pacifico 七套字体到/tmp，再解压进fonts/对应子目录；LaTeX 通过fontspec+\setmainfont{Source Serif Pro}、\setsansfont{Roboto}、\setmonofont{Source Code Pro}等命令按文件名规则（如fonts/roboto/Roboto-.ttf）加载（见 cheatsheets.tex 第 51-89 行）。若希望 Matplotlib 也能发现这些字体，可在$HOME/.config/fontconfig/fonts.conf中加入<dir>/path/to/cheatsheets/fonts/</dir>目录声明（详见 README.md）。
2. 生成全部插图：figures目标执行cd scripts && for script in *.py; do MPLBACKEND="agg" python $script; done，在纯 Agg 后端下批量运行 scripts/ 目录内 30 余个绘图脚本（如 scripts/anatomy.py、basic-plots.py、colormaps.py、tick-locators.py、tip-hatched.py等），输出到figures/；随后用pdfcrop对adjustments.pdf、annotate.pdf、colornames.pdf、tick-formatters.pdf等 12 个图执行白边裁剪。所有绘图脚本共用styles/base.mplstyle与styles/plotlet.mplstyle等自定义样式，例如 scripts/anatomy.py 通过mpl.style.use(ROOT_DIR / 'styles/base.mplstyle')统一风格，并用np.random.seed(123)固定随机种子保证图形可复现。
3. 编译 PDF 并转 PNG：xelatex cheatsheets.tex编译两页速查表，随后convert -density 150 -alpha remove -depth 8 cheatsheets.pdf -scene 1 cheatsheets.png用 ImageMagick 转出首页所需的cheatsheets-1.png/cheatsheets-2.png；三份讲义同样经xelatex编译并转 PNG。
4. 构建 Sphinx 文档：docs目标执行make -C docs/ html（见 docs/Makefile，注意默认带-W将警告视为错误），再把cheatsheets*.p*与handout-*.p*拷贝进_build/html，最终渲染出docs/index.rst所定义的下载首页。
5. 质量检查：check目标依次运行 check-matplotlib-version.py、check-num-pages.sh（断言速查表 2 页、各讲义 1 页）、check-diffs.py 与 check-links.py（校验 PDF 内链接有效性），确保每次构建产物符合预期。

依赖清单集中在 requirements/requirements.in（如sphinx_design、mpl_sphinx_theme、XeLaTeX、ImageMagick 等），经 requirements/Makefile 固化到 requirements/requirements.txt，贡献者在干净环境中可通过make requirements一键对齐工具链。

参与贡献与许可

首页 Contribute 区块明确表示：Issues、建议与 Pull Request 均被欣然接受，这是官方仓库对社区贡献的正式邀请。结合上文可见，一套完整贡献路径大致为：修改scripts/*.py生成新的示例图、调整cheatsheets.tex/handout-*.tex中的排布与说明、在docs/index.rst中更新预览与链接，最后运行make全量构建并执行make check自检。

版权与许可方面，速查表与三份讲义页脚均标注「Copyright (c) 2021 Matplotlib Development Team」「Released under a CC-BY 4.0 International License」「Supported by NumFOCUS」，仓库根目录的 LICENSE.txt 提供完整许可文本；logos/numfocus.png则作为赞助方标识出现在速查表末页。当前仓库所有产出物均标注 Matplotlib 3.10.8 版本，读者在较新或较旧版本下使用速查表时，应对个别 API 差异保持留意（例如内置样式随版本演进的取舍）。