[PATCH v2 6/7] doc: make pdfdocs: Increase the maximum list depth

Adriano Carvalho adrianocarvalho.pt at gmail.com
Mon Oct 6 00:10:13 CEST 2025


According to sphinx-build's documentation, by default the maximum list
depth (latex_elements.maxlistdepth in conf.py) is six, which is not
enough for U-Boot's documentation, leading to errors. See below.

This commit sets maxlistdepth to ten, solving the problem.

If maxlistdepth is not set to ten, this is what I get with
docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

(myenv) uboot at 35c89b9ab70e:~/u-boot$ make pdfdocs
[...]
xelatex  'android.tex'
[...]
Output written on android.pdf (28 pages).
[...]
xelatex  'api.tex'
[...]
Output written on api.pdf (431 pages).
[...]
xelatex  'arch.tex'
[...]
Output written on arch.pdf (62 pages).
[...]
xelatex  'board.tex'
[...]

[361]

! LaTeX Error: Too deeply nested.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H <return>  for immediate help.
 ...

l.26806 \begin{itemize}

?
! Emergency stop.
 ...

[...]

Output written on board.pdf (365 pages).
Transcript written on board.log.
make[2]: *** [Makefile:29: board.pdf] Error 1
make[1]: *** [doc/Makefile:95: pdfdocs] Error 2
make: *** [Makefile:2687: pdfdocs] Error 2

This solves the problem with the pdfdocs target (in
docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025 at
least).

The docs have been updated as well, assuming the issues with the pdfdocs
target are fixed.

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt at gmail.com>
---
 doc/build/documentation.rst | 5 ++---
 doc/conf.py                 | 4 ++++
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 1342c71addd..47b849c7d8e 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -88,9 +88,8 @@ The *pdfdocs* target is meant to be used to build PDF documentation:
     # Deactivate the Python environment
     deactivate
 
-However, as of v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
-
-We can use texi2pdf instead:
+The *texinfodocs* target, together with *texi2pdf*, can also be used to build
+PDF documentation:
 
 .. code-block:: bash
 
diff --git a/doc/conf.py b/doc/conf.py
index 84d028feda8..3405fe428f7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -376,6 +376,10 @@ latex_elements = {
         \\setromanfont{DejaVu Serif}
         \\setmonofont{DejaVu Sans Mono}
      ''',
+    #
+    # Deep nesting; tell latex to cope.
+    #
+    "maxlistdepth": "10",
 }
 
 # At least one book (translations) may have Asian characters
-- 
2.34.1



More information about the U-Boot mailing list