如何使用rst2pdf将本地磁盘图片设为reStructuredText的PDF背景？

rst2pdf对Raw HTML的样式支持有限，直接用HTML设置背景的方法无法生效，推荐以下两种可行方案：

方法一：自定义CSS样式表 #

rst2pdf支持解析专用CSS规则，通过样式表定义页面背景：

1. 创建样式文件（例如bg_style.css），写入规则：

@page {
    background-image: url('/home/mpenning/ciscoconfparse_logo_bw_01.png');
    background-position: center;
    background-repeat: no-repeat;
    background-size: contain; /* 可替换为cover、具体尺寸，按需调整 */
    background-color: white;
}

2. 生成PDF时指定该样式表：

rst2pdf --stylesheet=bg_style.css 你的文档.rst -o 输出文件.pdf

方法二：使用页面模板 #

如果需要对不同页面设置不同背景，可使用rst2pdf的页面模板功能：

1. 在reStructuredText文档开头定义模板：

.. raw:: pdf

   PageTemplate(name='bg_template', background='/home/mpenning/ciscoconfparse_logo_bw_01.png', bgroundpos='center', bgroundrepeat='no-repeat')

2. 全局应用模板：

.. raw:: pdf

   SetPageTemplate(bg_template)

也可针对特定章节切换模板，用完后恢复默认：

.. raw:: pdf

   SetPageTemplate(bg_template)

你的章节内容...

.. raw:: pdf

   SetPageTemplate(default)

注意事项 #

• 确保图片路径为绝对路径，或相对于rst文档的相对路径，保证rst2pdf能读取到
• 可调整background-size、background-position等参数优化显示效果
• 若背景图颜色较深，建议同步设置文本颜色提升可读性

内容的提问来源于stack exchange，提问作者Mike Pennington