如何避免“太深嵌套”使用Sphinx创建PDF时出错？ [英] How to avoid the "too deeply nested" error when creating PDFs with Sphinx?

问题描述

我有一个相当复杂的项目，具有相当大的文档。
将正常的用户指南转换为带有Sphinx的PDF，通过使latexpdf 工作得很好。但是，如果我还想包含所有函数，类和模块文档的库引用，命令将失败：

  ！ LaTeX错误：太深嵌套。 
  

手动减少嵌套不是一个选择。 Sphinx内部嵌套参数描述，功能描述，模块描述和whatnot。因此，在每种情况下，如何减少嵌套几乎是不可能的。

解决方案

我通过添加一些latex语句来解决问题狮身人面像前导。
因此，我在sphinx 源文件夹中创建了一个新的 latex_preamble.tex 文件。它只包含以下两个命令：

  \usepackage {enumitem} 
 \setlistdepth {99} 
  

此外，在 conf.py 文件中，在我的源文件夹中，我更改了以下内容（您可以在 conf.py

中查找 latex_elements 变量， code>文件，通常被注释掉）：

  fh = open（'latex_preamble.tex'，'r + '）
 PREAMBLE = fh.read（）
 fh.close（）
 latex_elements = {
＃LaTeX前导码的附加内容。 
'preamble'：PREAMBLE，
} 
  

因此，现在sphinx使用 enumitem 允许任意嵌套的程序包。我想现在， enumitem 应该是任何乳胶分发的一部分。我不需要安装包。此外，这也是阅读文档的框。

I have a fairly complex project with a fairly large documentation. Converting the normal user guide to PDF with Sphinx via make latexpdf works quite well. However, if I also want to include the library reference with all function, class, and module documentations, the command fails with:

! LaTeX Error: Too deeply nested.

Manually reducing the nesting is not an option. Sphinx internally nests parameter descriptions, function descriptions, module descriptions and whatnot. So figuring out in each case how to reduce the nesting is almost impossible.

解决方案

I solved the problem by adding some latex statements to the sphinx preamble. Accordingly, I created a new latex_preamble.tex file in my sphinx source folder. It contains only the following two commands:

\usepackage{enumitem}
\setlistdepth{99}

Moreover, In the conf.py file, also within my source folder, I changed the following (you can lookout for the latex_elements variable in the conf.py file, it is usually commented out):

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

Hence, now sphinx uses the enumitem package that allows arbitrary nesting. I guess nowadays enumitem should be part of any latex distribution. I did not need to install the package. Moreover, this also worked out of the box on read the docs.

这篇关于如何避免“太深嵌套”使用Sphinx创建PDF时出错？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！