Search code examples
pythonlatexpdf-generationpython-sphinx

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

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.

Solution

  • 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.