向使用 rst2pdf 和 Sphinx 生成的 PDF 添加页眉和页脚

Question

我继承了使用 reStructuredText 和 Sphinx 构建的用户指南，我们希望（并且可以）使用 rst2pdf 与 Sphinx 集成来生成 PDF。我们想做的一件事是将自定义页眉和页脚应用到文档的每一页（a'la“草稿 - 不用于发布”或“版本 x.y.z”），但没有明显的（对我来说） ）方法来做到这一点。 rst2pdf 命令支持指定

--footer="..."

和

--header="..."

，但 PDF 配置指令中似乎没有可以在 Sphinx

conf.py

中指定的类似选项。尽管 RST 确实支持 header 和 foot 指令，但 Sphinx 文档明确警告不要使用它们。

我认为可能可以使用rst2pdf样式表来设置它，但我也花了一些时间来理解自定义样式表如何与/扩展/覆盖现有样式表（如果有的话）。

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

Answer 1

我得出的答案是根据以下信息拼凑而成：

• rst2pdf

  文档对styles和多个样式表的讨论，它告诉我样式表的顺序很重要，并且自定义样式表只需要定义要覆盖的内容或添加到以前的样式表中
内置样式的 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

和

letter

rst2pdf

样式表，然后是我的自定义 draft rst2pdf样式表，并在每个页面的顶部和底部生成所需的横幅文本。