将页眉和页脚添加到使用rst2pdf和spinx生成的PDF中

Question

我继承了一个使用reStructuredText和Sphinx构建的用户指南，我们希望(并且可以(使用rst2pdf与Sphinx的集成来生成PDF。我们想做的一件事是将自定义页眉和页脚应用于文档的每一页("la"Draft-Not for Release"或"Version x.y.z"(，但(对我来说(没有明显的方法。rst2pdf命令支持指定--footer="..."和--header="..."，但在PDF配置指令中似乎没有可以在Sphinxconf.py中指定的类似选项。尽管RST确实支持header和foot指令，但Sphinx文档明确警告不要使用它们。

我认为可以使用rst2pdf样式表来设置它，但我也有一点时间了解自定义样式表如何与/extend/override现有样式表交互(如果有的话(。

因此，我正在寻找一些关于如何使用rst2pdf和Sphinx将页眉和页脚干净地添加到每个页面的指导。

Answer 1

我得到的答案是将中的信息拼接在一起

• rst2pdf文档对样式和多个样式表的讨论，教会了我样式表的排序很重要，自定义样式表只需要定义被覆盖或添加到以前的样式表中的内容
• 构建的instyles的rst2pdf源代码显示了样式表最好用YAML表示，以及它们的结构，以及rst2pdf样式Python模块的源代码，以更好地理解rst2pdf如何解析样式表文件的位置和扩展名
• rst2pdf问题中有一个使用样式表呈现页脚的示例

所以我创建了一个名为draft.yaml的样式表，并将其放在文档源代码的_styles子目录中，看起来像：

pageTemplates:
decoratedPage:
defaultFooter: |
.. class:: right
###Page###

.. class:: draft
DRAFT - DO NOT RELEASE

defaultHeader: &draftCentered |
.. class:: draft
DRAFT - DO NOT RELEASE

mainPage: &draftTopAndBottom
defaultFooter: *draftCentered
defaultHeader: *draftCentered
showFooter: true
showHeader: true
coverPage: *draftTopAndBottom
emptyPage: *draftTopAndBottom

styles:
draft: {alignment: center, parent: bodytext, fontName: fontSansBold}

注意到样式表处理器支持锚点和别名，我只是修改现有的页面模板，在所有页面上包括默认的页眉和页脚，我可以定义并使用自己的样式应用于页眉和页脚。我曾想尝试使用表格语法将页码和页脚横幅放在同一行，就像可以在文档正文中这样做一样，但它一直试图将表格语法视为引用替换。

为了使用Sphinx和rst2pdf，我需要在conf.py中添加一些额外的配置信息——首先将rst2pdf.pdfbuilder添加到extensions的列表中，然后使用以下变量定义来控制PDF渲染：

# -- Options for PDF output ----------------------------------------------
pdf_documents = [('index', u'mydoc', u'My Documentation', u'My Project'),]
pdf_stylesheets = ['sphinx', 'letter', 'draft']
pdf_style_path = ['source/_styles']

有了这个配置和样式表，使用pdf构建器运行sphinx，将在rst2pdf默认值之上应用内置的sphinx和letterrst2pdf样式表，然后应用我的自定义draftrst2pdf样式表，并在每个页面的顶部和底部生成所需的标题文本。