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

Question

我继承了使用reStructuredText和Sphinx构建的用户指南，我们希望(也可以)从指南中生成一个使用rst2pdf与狮身人面像集成的PDF。我们想做的一件事是将自定义的页眉和页脚应用到文档的每一页(a‘’la“草稿-不是用于发布”或"Version x.y.z")，但是没有一种明显的方法(对我来说)。rst2pdf命令支持指定--footer="..."和--header="..."，但在--header="..."配置指令中似乎没有类似的选项可以在狮身人面像中指定。尽管RST确实支持头指令和脚指令，但Sphinx文档明确警告不要使用它们。

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

所以，我要找的是一些关于如何使用rst2pdf和狮身人面像干净地将头和页脚添加到每个页面的指导。

Answer 1

我想出的答案是把信息拼凑在一起：

• rst2pdf文档对样式和多个样式表的讨论告诉我，样式表的排序很重要，定制样式表只需要定义要覆盖或添加到以前的样式表中的内容。
• 说明样式表最好表示为YAML的构建实例的rst2pdf源代码，以及它们的结构方式，以及如何与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}

注意到样式表处理器支持锚和别名，我只是简单地修改现有的页面模板，以便在所有页面上包含一个默认的页眉和页脚，并且可以定义并使用自己的样式在页眉和页脚中应用。我本想尝试使用表语法将页码和页脚横幅放在同一行中，比如可以在文档正文中作为在这里显示来完成，但它一直试图将表语法作为引用替代。

为了使它与狮身人面像和rst2pdf一起工作，我需要在conf.py中添加一些附加的配置信息--首先将rst2pdf.pdfbuilder添加到extensions列表中，然后使用以下变量定义来控制extensions呈现：

# -- 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，将在sphinx默认设置的基础上应用内置sphinx和letter rst2pdf样式表，然后应用自定义的draft rst2pdf样式表，并在每个页面的顶部和底部生成所需的横幅文本。