Rst2pdf与Sphinx：自定义PDF样式的文件格式困惑

我查阅多方资料后，仍对Rst2pdf自定义PDF样式的定义方式感到困惑，不清楚应该采用.styles还是.json格式？

当前目录结构与配置文件 #

我的配置文件路径：/home/sachin/Workspace/Sootballs/pa-amr/docs/.rst2pdf/config/rst2pdf.conf

配置内容：

# This is an example config file. Modify and place in ~/.rst2pdf/config

[general]
# A comma-separated list of custom stylesheets. Example:

# A comma-separated list of custom stylesheets. Example:
# stylesheets="fruity.json,a4paper.json,verasans.json"
stylesheets="paamr.json"

# A colon-separated list of folders to search for stylesheets. Example:
# stylesheet_path="~/styles:/usr/share/styles"
# stylesheet_path="~/Workspace/Sootballs/pa-amr/docs/paamr.style"
stylesheet_path="../styles/paamr.style"   // 这里困惑：这样定义样式路径对吗？

我尝试的两种样式文件 #

1. .styles格式（YAML语法） #

文件路径：/home/sachin/Workspace/Sootballs/pa-amr/docs/styles/paamr.style
内容：

# List any fonts you would like to embed in the PDF here
embeddedFonts: []

# Default page setup.  Can be overridden by including other
# stylesheets with -s

pageSetup:
  size: A4
  width: null
  height: null
  margin-top: 2cm
  margin-bottom: 2cm
  margin-left: 2cm
  margin-right: 2cm
  margin-gutter: 0cm
  spacing-header: 5mm
  spacing-footer: 5mm

2. .json格式 #

文件路径：/home/sachin/Workspace/Sootballs/pa-amr/docs/_styles/paamr.json
内容：

{
    "fontsAlias": {
      "stdFont": "Times-Roman",
      "stdBold": "Times-Bold",
      "stdItalic": "Times-Italic",
      "stdBoldItalic": "Times-BoldItalic"
    }
}

解答 #

1. 格式选择：两种都支持
   Rst2pdf同时支持.json和.styles（YAML语法）格式的样式文件，两者功能等价，仅语法不同。可根据偏好选择：

• 偏好层级清晰的简洁语法选YAML格式（.styles）
• 习惯标准键值对语法选JSON格式

2. 配置文件的错误修正
   你的stylesheet_path配置有误：该参数用于指定存放样式文件的文件夹路径，而非具体样式文件的路径。例如：
   如果.styles文件放在/home/sachin/Workspace/Sootballs/pa-amr/docs/styles/目录下，配置应改为：

stylesheet_path="../styles"

随后stylesheets参数对应样式文件名，若用.styles文件则写：

stylesheets="paamr.style"

若用.json文件，只需将其放入stylesheet_path指定的文件夹，再把stylesheets设为"paamr.json"即可。

3. 样式文件语法注意

• .styles是YAML格式，需保证缩进正确（你的示例中embeddedFonts前多了不必要的空格，需与pageSetup同级）
• .json格式要确保语法规范，键名引号、逗号等符号不能遗漏

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