使用 Sphinx 创建 PDF 时如何避免 "too deeply nested" 错误？

Question

我有一个相当复杂的项目，其中包含相当多的文档。通过 make latexpdf 使用 Sphinx 将普通 用户指南 转换为 PDF 效果很好。但是，如果我还想包含包含所有函数的库引用 class 和模块文档，则命令会失败：

! LaTeX Error: Too deeply nested.

手动减少嵌套不是一种选择。 Sphinx 内部嵌套了参数说明、功能说明、模块说明等等。因此，在每种情况下都弄清楚如何减少嵌套几乎是不可能的。

Answer 1

我通过在 sphinx 序言中添加一些 latex 语句解决了这个问题。因此，我在我的 sphinx source 文件夹中创建了一个新的 latex_preamble.tex 文件。它只包含以下两个命令：

\usepackage{enumitem}
\setlistdepth{99}

此外，在 conf.py 文件中，也在我的 source 文件夹中，我更改了以下内容（您可以在conf.py文件，一般是注释掉的）：

fh = open('latex_preamble.tex', 'r+')
PREAMBLE = fh.read()
fh.close()
latex_elements = {
# Additional stuff for the LaTeX preamble.
'preamble': PREAMBLE,
}

因此，现在sphinx使用了允许任意嵌套的enumitem包。我想现在 enumitem 应该是任何乳胶发行版的一部分。我不需要安装这个包。此外，这在 read the docs.

上也是开箱即用的

使用 Sphinx 创建 PDF 时如何避免 "too deeply nested" 错误？

How to avoid the "too deeply nested" error when creating PDFs with Sphinx?

python

latex

pdf-generation

python-sphinx