[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