如何轻松修复 Sphinx 创建的 PDF 的边距？

【问题标题】：How do I fix the margins on PDFs created by Sphinx easily?如何轻松修复 Sphinx 创建的 PDF 的边距？
【发布时间】：2017-04-01 06:14:16
【问题描述】：

我有一个 Django 项目，我使用 Sphinx 来创建我的文档。我浏览了 sphinx-apidoc 并运行了“make latexpdf”。生成的文档有很多行从页边空白处流出。除了边距问题，索引中的行开始相互溢出。

是否有解决这些问题的简单方法（或创建 PDF 文档的更简单方法）？

如果可能，ELI5（我不精通 LaTeX）

【问题讨论】：

提供可重现的 Python 和 Sphinx 示例和版本。没有它，我唯一的建议是不要使用等宽字体，将等宽字体设置为更小的尺寸，或者使用更窄的字体。在Pyramid PDF documentation 的索引条目中，我们不使用等宽字体。我们曾经遇到过长行代码块没有正确包装的问题，但最近版本的 Sphinx 似乎已经解决了这个问题。在我们的source code repo 中查找示例。

【解决方案1】：

添加到conf.py后，索引中的溢出行情况应该会有所改善：

latex_elements = {
    'printindex': '\\footnotesize\\raggedright\\printindex',
}

或者，您可以从其特殊的文档类切换到开箱即用的类似（甚至更好）的日语；-)

TeX 本身并不总是知道如何插入换行符：毕竟它擅长自然语言的断字。但正如 cmets Sphinx 中指出的那样，自 1.4.2 以来，Sphinx 强制 LaTeX 处理更好的长代码行。

从最近的 1.5.3 开始，用户可以自定义页边距，查看http://www.sphinx-doc.org/en/stable/latex.html#the-sphinx-latex-style-package-options 获取可通过'sphinxsetup' 配置的 hmargin 和 vmargin 的文档。

【讨论】：