rst2pdf命令行选项全解：20+个参数助你高效生成PDF-平芜编程栈

rst2pdf命令行选项全解：20+个参数助你高效生成PDF

【免费下载链接】rst2pdfUse a text editor. Make a PDF.项目地址: https://gitcode.com/gh_mirrors/rs/rst2pdf

rst2pdf 是一款开源的 PDF 生成工具，口号就是「Use a text editor. Make a PDF.」——它让你用纯文本编辑器写 reStructuredText（RST）文档，然后直接生成排版精美的 PDF，完全绕开 LaTeX 的复杂流程。

本文带你一次性看懂rst2pdf 命令行选项：从最常用的输出、样式表参数，到页眉页脚、分页控制、图片与字体等高级选项，全部 40 个参数分类拆解。读完这篇 rst2pdf 使用教程，你就能熟练组合参数，生成专业级 PDF 文档。

安装后，生成 PDF 只需一条命令：

$ rst2pdf 文档名.rst 输出.pdf

例如把项目里的测试文档转换为 PDF：

$ rst2pdf tests/input/source.rst output.pdf

不确定有哪些选项？随时用-h查看帮助。所有命令行参数都在源码 rst2pdf/createpdf.py 的parse_commandline()函数中定义。

💡 上面这张图正是测试用例tests/input/test_background.yaml中通过background属性指定的页面背景，说明 rst2pdf 支持整页背景图片排版。

参数	作用
`文件名.rst 输出.pdf`	位置参数：输入文档与输出路径（可省略输出，默认写 stdout）
`-o, --output FILE`	指定 PDF 输出文件（不能与第二个位置参数同时使用）
`--config FILE`	指定配置文件，默认`~/.rst2pdf/config`，可批量预设参数默认值
`-s, --stylesheets FILE`	加载自定义样式表（YAML），可多次使用，逗号分隔

典型组合：

$ rst2pdf -o book.pdf -s rst2pdf/styles/dejavu.yaml 文档.rst

项目自带 70 多套内置样式表，位于 rst2pdf/styles/ 目录，包括 A4/A5/letter 页面尺寸、dejavu字体方案、solarized-dark代码高亮主题等，按需引用即可。

参数	作用
`--stylesheet-path DIR`	添加样式表搜索路径
`--font-path DIR`	添加字体搜索路径（支持 TTF 和 Type1 字体嵌入）
`--print-stylesheet`	打印默认样式表并退出（查看内置样式的神器）
`-l, --language LANG`	设置连字符与 docutils 本地化语言，默认`en_US`
`--smart-quotes VALUE`	将 ASCII 引号、省略号、破折号转换为排版正确的形式

想看看 rst2pdf 到底内置了哪些样式属性？一条命令全部导出：

$ rst2pdf --print-stylesheet > default.yaml

导出的内容即 rst2pdf/styles/styles.yaml 定义的完整默认样式，可作为你自定义样式表的起点。

参数	作用
`--header HEADER`	文档未指定时的默认页眉（支持`###Page###`、`###Section###`占位符）
`--footer FOOTER`	文档未指定时的默认页脚
`--section-header-depth N`	页眉页脚中章节标题替换`###Section###`的最大深度，默认 2
`-b, --break-level LEVEL`	多少级及更高层级的章节自动从新页开始，默认 0
`--break-side VALUE`	章节起始页控制：`even`/`odd`/`any`
`--first-page-on-right`	双面书籍样式，正文第一页从右侧开始
`--blank-first-page`	在文档开头插入一个空白页

书籍风格示例：让每个一级章节都从新的一页开始，页脚显示页码：

$ rst2pdf -b 1 --footer "第 ###Page### 页" 文档.rst

上图来自示例文档 doc/montecristo/montecristo.rst，它正是用.. header::和.. footer::指令配合###Section###、###Page###占位符实现的页眉页脚效果。

参数	作用
`--default-dpi NUMBER`	像素尺寸对象的 DPI，默认 300，直接影响插图大小
`--fit-background-mode MODE`	背景图适配方式：`scale`/`scale_width`/`center`
`--fit-literal-mode MODE`	代码块超宽时的处理：`error`/`overflow`/`shrink`/`truncate`，默认`shrink`
`--real-footnotes`	脚注显示在定义处的页面底部
`--inline-footnotes`	脚注以行内方式显示
`--no-footnote-backlinks`	禁用脚注回链
`--repeat-table-rows`	跨页表格时重复表头行
`--inline-links`	链接以括号显示目标而非可点击链接
`--baseurl URL`	相对 URL 的基准地址，默认当前目录

测试套件中大量使用大尺寸图片（如本图 1333x2000）验证--default-dpi的缩放行为：同一张图片，DPI 设为 300 和 100 时，PDF 中的物理尺寸会相差三倍。

参数	作用
`-v, --verbose`	打印调试信息
`--very-verbose`	打印更详细的调试信息
`-q, --quiet`	减少输出信息
`--version`	打印版本号并退出
`--show-frame-boundary`	显示页面分栏边框（调试布局必备）
`-e, --extension-module FILE`	加载 Python 扩展模块，可自定义指令与角色
`--record-dependencies FILE`	将输出文件依赖关系写入指定文件
`--strip-elements-with-class CLASS`	从输出中移除指定 class 的元素，可多次使用
`--raw-html`	支持嵌入原始 HTML
`--custom-cover FILE`	指定封面模板文件，默认`cover.tmpl`
`--use-floating-images`	让`:align:`属性的图片表现更接近 rst2html
`--use-numbered-links`	章节编号时，链接文字中也带上编号
`--date-invariant`	不在 PDF 中写入当前日期（保证输出可复现）

实战：调试布局问题

当排版不符合预期时，先打开分栏边框看看内容落在了哪里：

$ rst2pdf -v --show-frame-boundary 文档.rst

项目内置的扩展模块示例位于 rst2pdf/extensions/ 目录，可直接用-e参数加载。

最小可用命令：rst2pdf 文档.rst 输出.pdf
压缩文件：rst2pdf -c 文档.rst
换字体主题：rst2pdf -s rst2pdf/styles/serif.yaml 文档.rst
书籍排版：rst2pdf -b 1 --break-side odd --first-page-on-right 文档.rst
打印就绪：rst2pdf --smart-quotes 1 --repeat-table-rows --fit-literal-mode shrink 文档.rst
代码库依赖追踪：rst2pdf --record-dependencies deps.txt 文档.rst
固定输出（CI 场景）：rst2pdf --date-invariant 文档.rst