[PATCH 0/7] doc: make pdfdocs: Address issues with the make pdfdocs target

[PATCH 0/7] doc: make pdfdocs: Address issues with the make pdfdocs target

[Adriano Carvalho]

This patch series address several issues that were affecting the make pdfdocs target.

In the end, the make pdfdocs could be considered fixed. It is at least with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025.

The thing is fixed only after the 6th commit. Each commit solves one issue, in the order as they appeared. I hope it makes sense.

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>

Adriano Carvalho (7):
  doc: make pdfdocs: Specify texlive-xetex as a prerequisite
  doc: make pdfdocs: Update the description with the needed steps
  doc: make pdfdocs: Add pip install pytest to the list of needed steps
  doc: make pdfdocs: Ensure SVG files are converted to PDF before the
    compilation of *.tex files
  doc: make pdfdocs: Update empty SVG file to something, otherwise
    compilation of the *.tex files fails
  doc: make pdfdocs: Increase the maximum list depth
  doc: make pdfdocs: Remove redundant "-j" option

 doc/Makefile                          |   1 -
 doc/build/documentation.rst           |  24 +++++++++++++++++++++---
 doc/conf.py                           |   6 +++++-
 doc/develop/pics/spl_before_reloc.svg | Bin 0 -> 239 bytes
 4 files changed, 26 insertions(+), 5 deletions(-)

-- 
2.48.1

[PATCH 1/7] doc: make pdfdocs: Specify texlive-xetex as a prerequisite

[Adriano Carvalho]

If I don't apt install texlive-xetex, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
  HOSTCC  scripts/basic/fixdep
doc/Makefile:89: The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.
  SKIP    Sphinx pdfdocs target.

NOTE: This won't completely fix the pdfdocs target. See next commit(s).

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
---
 doc/build/documentation.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 098c96a4c4f..68d7e11c572 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -16,6 +16,8 @@ the following dependencies are needed to build the documentation:
 
 * texinfo (if building the `Infodoc documentation`_)
 
+* texlive-xetex (if building the `PDF documentation`_ through the *pdfdocs* target)
+
 HTML documentation
 ------------------
 
-- 
2.48.1

Re: [PATCH 1/7] doc: make pdfdocs: Specify texlive-xetex as a prerequisite

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 793 bytes --]

On Mon, Aug 25, 2025 at 11:44:44PM +0100, Adriano Carvalho wrote:
> If I don't apt install texlive-xetex, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:
> 
> uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
>   HOSTCC  scripts/basic/fixdep
> doc/Makefile:89: The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.
>   SKIP    Sphinx pdfdocs target.
> 
> NOTE: This won't completely fix the pdfdocs target. See next commit(s).
> 
> Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
> ---
>  doc/build/documentation.rst | 2 ++
>  1 file changed, 2 insertions(+)

Please follow-up with a patch to tools/docker/Dockerfile so that we can
add pdfdocs to CI later, thanks.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/7] doc: make pdfdocs: Specify texlive-xetex as a prerequisite

[E Shattow]

On 8/25/25 15:44, Adriano Carvalho wrote:
> If I don't apt install texlive-xetex, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:
> 
> uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
>   HOSTCC  scripts/basic/fixdep
> doc/Makefile:89: The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.
>   SKIP    Sphinx pdfdocs target.
> 
> NOTE: This won't completely fix the pdfdocs target. See next commit(s).
> 
> Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
> ---
>  doc/build/documentation.rst | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
> index 098c96a4c4f..68d7e11c572 100644
> --- a/doc/build/documentation.rst
> +++ b/doc/build/documentation.rst
> @@ -16,6 +16,8 @@ the following dependencies are needed to build the documentation:
>  
>  * texinfo (if building the `Infodoc documentation`_)
>  

> +* texlive-xetex (if building the `PDF documentation`_ through the *pdfdocs* target)
> +

needs one additional package recommended:

* texlive-xetex texlive-fonts-recommended (if building the `PDF
documentation`_ through the *pdfdocs* target)

>  HTML documentation
>  ------------------
>  

-E

[PATCH 2/7] doc: make pdfdocs: Update the description with the needed steps

[Adriano Carvalho]

It is not clear that before "make pdfdocs" it is also necessary to install "doc/sphinx/requirements.txt".
If I don't install "doc/sphinx/requirements.txt", this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
  SPHINX  latexdocs --> file:///home/uboot/u-boot/doc/output/latex
  PARSE   include/linker_lists.h
Running Sphinx v4.3.2
Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.
loading translations [en]... done

Extension error:
Could not import extension sphinx-prompt (exception: No module named 'sphinx-prompt')
make[1]: *** [doc/Makefile:84: latexdocs] Error 2
make: *** [Makefile:2686: pdfdocs] Error 2

A "t" was also missing in "documenation". This commit fixes that also.
NOTE: This won't completely fix the pdfdocs target. See next commit(s).

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
---
 doc/build/documentation.rst | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 68d7e11c572..2540f3973d2 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -65,8 +65,22 @@ The *infodocs* target builds both a texinfo and an info file:
 PDF documentation
 -----------------
 
-The *pdfdocs* target is meant to be used to build PDF documenation.
-As v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
+The *pdfdocs* target is meant to be used to build PDF documentation:
+
+.. code-block:: bash
+
+    # Create Python environment 'myenv'
+    python3 -m venv myenv
+    # Activate the Python environment
+    . myenv/bin/activate
+    # Install build requirements
+    python3 -m pip install -r doc/sphinx/requirements.txt
+    # Build the documentation
+    make pdfdocs
+    # Deactivate the Python environment
+    deactivate
+
+However, as of v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
 
 We can use texi2pdf instead:
 
-- 
2.48.1

Re: [PATCH 2/7] doc: make pdfdocs: Update the description with the needed steps

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1205 bytes --]

On Mon, Aug 25, 2025 at 11:44:45PM +0100, Adriano Carvalho wrote:

> It is not clear that before "make pdfdocs" it is also necessary to install "doc/sphinx/requirements.txt".
> If I don't install "doc/sphinx/requirements.txt", this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:
> 
> uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
>   SPHINX  latexdocs --> file:///home/uboot/u-boot/doc/output/latex
>   PARSE   include/linker_lists.h
> Running Sphinx v4.3.2
> Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.
> loading translations [en]... done
> 
> Extension error:
> Could not import extension sphinx-prompt (exception: No module named 'sphinx-prompt')
> make[1]: *** [doc/Makefile:84: latexdocs] Error 2
> make: *** [Makefile:2686: pdfdocs] Error 2
> 
> A "t" was also missing in "documenation". This commit fixes that also.
> NOTE: This won't completely fix the pdfdocs target. See next commit(s).

We should make it clear in the documentation on building the docs that
you need to do this for any build target.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH 3/7] doc: make pdfdocs: Add pip install pytest to the list of needed steps

[Adriano Carvalho]

If I don't install pytest, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
[...]
WARNING: autodoc: failed to import module 'test_bind'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_bootmenu'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_bootstage'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_button'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_efi_loader'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_net'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
WARNING: autodoc: failed to import module 'test_net_boot'; the following exception was raised:
No module named 'pytest' [autodoc.import_object]
[...]
build finished with problems, 7 warnings (with warnings treated as errors).
make[1]: *** [doc/Makefile:84: latexdocs] Error 1
make: *** [Makefile:2686: pdfdocs] Error 2

NOTE: This won't completely fix the pdfdocs target. See next commit(s).

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
---
 doc/build/documentation.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 2540f3973d2..69e0dc418b1 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -32,6 +32,7 @@ The *htmldocs* target is used to build the HTML documentation. It uses the
     . myenv/bin/activate
     # Install build requirements
     python3 -m pip install -r doc/sphinx/requirements.txt
+    python3 -m pip install pytest
     # Build the documentation
     make htmldocs
     # Deactivate the Python environment
-- 
2.48.1

Re: [PATCH 3/7] doc: make pdfdocs: Add pip install pytest to the list of needed steps

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1746 bytes --]

On Mon, Aug 25, 2025 at 11:44:46PM +0100, Adriano Carvalho wrote:

> If I don't install pytest, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:
> 
> uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
> [...]
> WARNING: autodoc: failed to import module 'test_bind'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_bootmenu'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_bootstage'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_button'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_efi_loader'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_net'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> WARNING: autodoc: failed to import module 'test_net_boot'; the following exception was raised:
> No module named 'pytest' [autodoc.import_object]
> [...]
> build finished with problems, 7 warnings (with warnings treated as errors).
> make[1]: *** [doc/Makefile:84: latexdocs] Error 1
> make: *** [Makefile:2686: pdfdocs] Error 2
> 
> NOTE: This won't completely fix the pdfdocs target. See next commit(s).
> 
> Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>

This should instead say to install test/py/requirements.txt and it is a
requirement for all doc targets.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

SVG files are not handled directly in the *.tex files.
This commit adds sphinxcontrib.inkscapeconverter (from the sphinxcontrib-svg2pdfconverter package) to sphinx's extensions in conf.py to ensure SVG files are converted to PDF before the compilation of *.tex files.
The needed steps are also updated and inkscape is specified as a dependency.

If I don't add sphinxcontrib.inkscapeconverter to sphinx's extensions, this is what I get with docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

uboot@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'
[...]

[152]
Chapter 14.

! LaTeX Error: Cannot determine size of graphic in boot_diagram_am62.svg (no Bo
undingBox).

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

l.11422 ...ncludegraphics{{boot_diagram_am62}.svg}

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

NOTE: This won't completely fix the pdfdocs target. See next commit(s).

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

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 69e0dc418b1..1e97085fc89 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -18,6 +18,8 @@ the following dependencies are needed to build the documentation:
 
 * texlive-xetex (if building the `PDF documentation`_ through the *pdfdocs* target)
 
+* inkscape (if building the `PDF documentation`_ through the *pdfdocs* target)
+
 HTML documentation
 ------------------
 
@@ -32,6 +34,7 @@ The *htmldocs* target is used to build the HTML documentation. It uses the
     . myenv/bin/activate
     # Install build requirements
     python3 -m pip install -r doc/sphinx/requirements.txt
+    python3 -m pip install sphinxcontrib-svg2pdfconverter
     python3 -m pip install pytest
     # Build the documentation
     make htmldocs
diff --git a/doc/conf.py b/doc/conf.py
index 84d028feda8..43472d5dc3d 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -48,7 +48,9 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
               'kernel_abi', 'kernel_feat', 'sphinx-prompt',
-              'sphinx_reredirects', 'sphinx.ext.autodoc' ]
+              'sphinx_reredirects', 'sphinx.ext.autodoc',
+              'sphinx_reredirects', 'sphinx.ext.autodoc',
+              'sphinxcontrib.inkscapeconverter' ]
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
-- 
2.48.1

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

On Mon, 25 Aug 2025 at 23:46, Adriano Carvalho
<adrianocarvalho.pt@gmail.com> wrote:
> [...]
> +              'sphinx_reredirects', 'sphinx.ext.autodoc',
> +              'sphinx_reredirects', 'sphinx.ext.autodoc',
> [...]

Even though it does no harm, this is a bug. I'll fix that in the next
revision. Sorry about that.

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 539 bytes --]

On Mon, Aug 25, 2025 at 11:44:47PM +0100, Adriano Carvalho wrote:

> SVG files are not handled directly in the *.tex files.
> This commit adds sphinxcontrib.inkscapeconverter (from the sphinxcontrib-svg2pdfconverter package) to sphinx's extensions in conf.py to ensure SVG files are converted to PDF before the compilation of *.tex files.
> The needed steps are also updated and inkscape is specified as a dependency.

This seems very heavy, is there not some other conversion we can do in
order to support PDF output?

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

On Tue, 26 Aug 2025 at 00:00, Tom Rini <trini@konsulko.com> wrote:
>
> On Mon, Aug 25, 2025 at 11:44:47PM +0100, Adriano Carvalho wrote:
>
> > SVG files are not handled directly in the *.tex files.
> > This commit adds sphinxcontrib.inkscapeconverter (from the sphinxcontrib-svg2pdfconverter package) to sphinx's extensions in conf.py to ensure SVG files are converted to PDF before the compilation of *.tex files.
> > The needed steps are also updated and inkscape is specified as a dependency.
>
> This seems very heavy, is there not some other conversion we can do in
> order to support PDF output?
>
> --
> Tom

The extension itself is quite simple.

inkscape on the other hand, according to apt-rdepends has 755
dependencies on Ubuntu 25.04.

rsvg-convert (librsvg2-bin) "only" has 179.

So, instead of sphinxcontrib.inkscapeconverter we can use
sphinxcontrib.rsvgconverter and reduce the number of dependencies
quite significantly.

Does this address your concern?

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1468 bytes --]

On Wed, Aug 27, 2025 at 12:47:56AM +0100, Adriano Carvalho wrote:
> On Tue, 26 Aug 2025 at 00:00, Tom Rini <trini@konsulko.com> wrote:
> >
> > On Mon, Aug 25, 2025 at 11:44:47PM +0100, Adriano Carvalho wrote:
> >
> > > SVG files are not handled directly in the *.tex files.
> > > This commit adds sphinxcontrib.inkscapeconverter (from the sphinxcontrib-svg2pdfconverter package) to sphinx's extensions in conf.py to ensure SVG files are converted to PDF before the compilation of *.tex files.
> > > The needed steps are also updated and inkscape is specified as a dependency.
> >
> > This seems very heavy, is there not some other conversion we can do in
> > order to support PDF output?
> >
> > --
> > Tom
> 
> The extension itself is quite simple.
> 
> inkscape on the other hand, according to apt-rdepends has 755
> dependencies on Ubuntu 25.04.
> 
> rsvg-convert (librsvg2-bin) "only" has 179.
> 
> So, instead of sphinxcontrib.inkscapeconverter we can use
> sphinxcontrib.rsvgconverter and reduce the number of dependencies
> quite significantly.
> 
> Does this address your concern?

This is getting closer, yes. Looking at v6.16 in the kernel, it looks
like rsvg-convert is a pre-req for pdfdocs there, so we should adopt
that (and whatever general updates need to be done) as part of
supporting pdfdocs as a target. I was unaware until now just how
difficult adding SVG to PDF output was, sorry for the churn here.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

On Wed, 27 Aug 2025 at 01:23, Tom Rini <trini@konsulko.com> wrote:
> [...]
> This is getting closer, yes. Looking at v6.16 in the kernel, it looks
> like rsvg-convert is a pre-req for pdfdocs there, so we should adopt
> that (and whatever general updates need to be done) as part of
> supporting pdfdocs as a target. I was unaware until now just how
> difficult adding SVG to PDF output was, sorry for the churn here.
>
> --
> Tom

No problem.

I'll take a look at what's being done in Linux.

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

> On Wed, 27 Aug 2025 at 01:23, Tom Rini <trini@konsulko.com> wrote:
> > [...]
> > This is getting closer, yes. Looking at v6.16 in the kernel, it looks
> > like rsvg-convert is a pre-req for pdfdocs there, so we should adopt
> > that (and whatever general updates need to be done) as part of
> > supporting pdfdocs as a target. I was unaware until now just how
> > difficult adding SVG to PDF output was, sorry for the churn here.
> >
> [---]

In Linux, for SVG to PDF conversion they rely on an sphinx-build
extension: Documentation/sphinx/kfigure.py

This extension supports other formats and conversions.

However, for this translation to occur, in *rst files you have to use:

.. kernel-image:: file.svg

Instead of:

.. image:: file.svg

(Also: kernel-figure instead of figure. In U-Boot ".. figure" is never used.)

Funny or not, kfigure.py is present in U-Boot (doc/sphinx/kfigure.py)
and it is already set as a sphinx-build extension.

So, in principle, we "only" need to replace all ".. image" with "..
kernel-image" (65 occurrences / 17 files). However, I did that, and
got:

sphinx.errors.ExtensionError: Handler <bound method
ImageCollector.process_doc of
<sphinx.environment.collectors.asset.ImageCollector object at
0x79380051bbe0>> for event 'doctree-read' threw an exception
(exception: 'uri')

And I still couldn't figure out a solution. I'll keep looking.

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

On Wed, 3 Sept 2025 at 02:14, Adriano Carvalho
<adrianocarvalho.pt@gmail.com> wrote:
> [...]
> So, in principle, we "only" need to replace all ".. image" with "..
> kernel-image" (65 occurrences / 17 files). However, I did that, and
> got:
>
> sphinx.errors.ExtensionError: Handler <bound method
> ImageCollector.process_doc of
> <sphinx.environment.collectors.asset.ImageCollector object at
> 0x79380051bbe0>> for event 'doctree-read' threw an exception
> (exception: 'uri')
> [...]

Actually, the right approach is to use ".. kernel-figure" not "..
kernel-image". The latter is never used in the kernel.

Using ".. kernel-figure" it works fine. The remaining patches are
still required though.

So, if you intend to remain aligned with Linux in the way the
Documentation is built, instead of this patch a new one is required
that replaces all instances of ".. image" with ".. kernel-image" (65
ccurrences / 17 files).

Please let me know how you'd like me to proceed.

Moreover, the infrastructure to build the Documentation is a bit
behind that of Linux. Not a lot but quite a few changes. Should I try
to issue a patch series to place U-Boot as in sync as possible with
Linux?

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1769 bytes --]

On Thu, Sep 04, 2025 at 02:24:57AM +0100, Adriano Carvalho wrote:
> On Wed, 3 Sept 2025 at 02:14, Adriano Carvalho
> <adrianocarvalho.pt@gmail.com> wrote:
> > [...]
> > So, in principle, we "only" need to replace all ".. image" with "..
> > kernel-image" (65 occurrences / 17 files). However, I did that, and
> > got:
> >
> > sphinx.errors.ExtensionError: Handler <bound method
> > ImageCollector.process_doc of
> > <sphinx.environment.collectors.asset.ImageCollector object at
> > 0x79380051bbe0>> for event 'doctree-read' threw an exception
> > (exception: 'uri')
> > [...]
> 
> Actually, the right approach is to use ".. kernel-figure" not "..
> kernel-image". The latter is never used in the kernel.
> 
> Using ".. kernel-figure" it works fine. The remaining patches are
> still required though.
> 
> So, if you intend to remain aligned with Linux in the way the
> Documentation is built, instead of this patch a new one is required
> that replaces all instances of ".. image" with ".. kernel-image" (65
> ccurrences / 17 files).
> 
> Please let me know how you'd like me to proceed.

We should switch to "kernel-image" and update our checkpatch.pl to
complain (and this might be acceptable to the linux kernel too, are
there instances of ".. image" ? I assume they too should be
kernel-image) so that we don't regress in easy to catch ways.

And then yes, getting the correct non-zero SVG for the TI example needs
to be done.

> Moreover, the infrastructure to build the Documentation is a bit
> behind that of Linux. Not a lot but quite a few changes. Should I try
> to issue a patch series to place U-Boot as in sync as possible with
> Linux?

This is a question for Heinrich. Thanks again for digging here!

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

Ping. Any update on this?

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

On Sat, 6 Sept 2025 at 00:09, Tom Rini <trini@konsulko.com> wrote:
>
> On Thu, Sep 04, 2025 at 02:24:57AM +0100, Adriano Carvalho wrote:
> > On Wed, 3 Sept 2025 at 02:14, Adriano Carvalho
> > <adrianocarvalho.pt@gmail.com> wrote:
> > > [...]
> > > So, in principle, we "only" need to replace all ".. image" with "..
> > > kernel-image" (65 occurrences / 17 files). However, I did that, and
> > > got:
> > >
> > > sphinx.errors.ExtensionError: Handler <bound method
> > > ImageCollector.process_doc of
> > > <sphinx.environment.collectors.asset.ImageCollector object at
> > > 0x79380051bbe0>> for event 'doctree-read' threw an exception
> > > (exception: 'uri')
> > > [...]
> >
> > Actually, the right approach is to use ".. kernel-figure" not "..
> > kernel-image". The latter is never used in the kernel.
> >
> > Using ".. kernel-figure" it works fine. The remaining patches are
> > still required though.
> >
> > So, if you intend to remain aligned with Linux in the way the
> > Documentation is built, instead of this patch a new one is required
> > that replaces all instances of ".. image" with ".. kernel-image" (65
> > ccurrences / 17 files).
> >
> > Please let me know how you'd like me to proceed.
>
> We should switch to "kernel-image" and update our checkpatch.pl to
> complain (and this might be acceptable to the linux kernel too, are
> there instances of ".. image" ? I assume they too should be
> kernel-image) so that we don't regress in easy to catch ways.
>
> And then yes, getting the correct non-zero SVG for the TI example needs
> to be done.
>
> > Moreover, the infrastructure to build the Documentation is a bit
> > behind that of Linux. Not a lot but quite a few changes. Should I try
> > to issue a patch series to place U-Boot as in sync as possible with
> > Linux?
>
> This is a question for Heinrich. Thanks again for digging here!
>
> --
> Tom

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 2472 bytes --]

On Tue, Sep 23, 2025 at 09:49:05PM +0100, Adriano Carvalho wrote:

> Ping. Any update on this?

Yes, a patch has been posted and is currently assigned to Heinrich. A
follow-up with a cleaner diagram has also been posted. If you would like
to rebase your work and in the cover list them as dependencies that
would be good. Thanks again for looking in to this!

> 
> Com os melhores cumprimentos. / Best regards.
> Adriano Carvalho
> 
> On Sat, 6 Sept 2025 at 00:09, Tom Rini <trini@konsulko.com> wrote:
> >
> > On Thu, Sep 04, 2025 at 02:24:57AM +0100, Adriano Carvalho wrote:
> > > On Wed, 3 Sept 2025 at 02:14, Adriano Carvalho
> > > <adrianocarvalho.pt@gmail.com> wrote:
> > > > [...]
> > > > So, in principle, we "only" need to replace all ".. image" with "..
> > > > kernel-image" (65 occurrences / 17 files). However, I did that, and
> > > > got:
> > > >
> > > > sphinx.errors.ExtensionError: Handler <bound method
> > > > ImageCollector.process_doc of
> > > > <sphinx.environment.collectors.asset.ImageCollector object at
> > > > 0x79380051bbe0>> for event 'doctree-read' threw an exception
> > > > (exception: 'uri')
> > > > [...]
> > >
> > > Actually, the right approach is to use ".. kernel-figure" not "..
> > > kernel-image". The latter is never used in the kernel.
> > >
> > > Using ".. kernel-figure" it works fine. The remaining patches are
> > > still required though.
> > >
> > > So, if you intend to remain aligned with Linux in the way the
> > > Documentation is built, instead of this patch a new one is required
> > > that replaces all instances of ".. image" with ".. kernel-image" (65
> > > ccurrences / 17 files).
> > >
> > > Please let me know how you'd like me to proceed.
> >
> > We should switch to "kernel-image" and update our checkpatch.pl to
> > complain (and this might be acceptable to the linux kernel too, are
> > there instances of ".. image" ? I assume they too should be
> > kernel-image) so that we don't regress in easy to catch ways.
> >
> > And then yes, getting the correct non-zero SVG for the TI example needs
> > to be done.
> >
> > > Moreover, the infrastructure to build the Documentation is a bit
> > > behind that of Linux. Not a lot but quite a few changes. Should I try
> > > to issue a patch series to place U-Boot as in sync as possible with
> > > Linux?
> >
> > This is a question for Heinrich. Thanks again for digging here!
> >
> > --
> > Tom

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Adriano Carvalho]

Is it ok to replace all instances of ".. image" with ".. kernel-image"
(65 occurrences / 17 files)?

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

On Wed, 24 Sept 2025 at 01:57, Tom Rini <trini@konsulko.com> wrote:
>
> On Tue, Sep 23, 2025 at 09:49:05PM +0100, Adriano Carvalho wrote:
>
> > Ping. Any update on this?
>
> Yes, a patch has been posted and is currently assigned to Heinrich. A
> follow-up with a cleaner diagram has also been posted. If you would like
> to rebase your work and in the cover list them as dependencies that
> would be good. Thanks again for looking in to this!
> [...]

Re: [PATCH 4/7] doc: make pdfdocs: Ensure SVG files are converted to PDF before the compilation of *.tex files

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 280 bytes --]

On Thu, Oct 02, 2025 at 01:06:27PM +0100, Adriano Carvalho wrote:

> Is it ok to replace all instances of ".. image" with ".. kernel-image"
> (65 occurrences / 17 files)?

Yes, that's fine. And a commit doing it makes sense, rather than one per
file/directory.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[PATCH 5/7] doc: make pdfdocs: Update empty SVG file to something, otherwise compilation of the *.tex files fails

[Adriano Carvalho]

There is one SVG file (doc/develop/pics/spl_before_reloc.svg) that is empty (0-byte) and because of that it is not translated to PDF leading to an error. See below.
This commit updates that file to something (i.e., an simple image with "TODO" written on it), solving the problem.

The error in docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:

uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
[...]
WARNING: cannot copy image file '/home/uboot/u-boot/doc/output/.doctrees/images/spl_before_reloc.pdf': /home/uboot/u-boot/doc/output/.doctrees/images/spl_before_reloc.pdf does not exist
[...]
build finished with problems, 1 warning (with warnings treated as errors).
make[1]: *** [doc/Makefile:84: latexdocs] Error 1
make: *** [Makefile:2686: pdfdocs] Error 2

NOTE: This won't completely fix the pdfdocs target. See next commit(s).

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
---
 doc/develop/pics/spl_before_reloc.svg | Bin 0 -> 239 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)

diff --git a/doc/develop/pics/spl_before_reloc.svg b/doc/develop/pics/spl_before_reloc.svg
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..917170799187a43d09c129e0c735326ad4c4db6e 100644
GIT binary patch
literal 239
zcmXYrO%8%E5QX=gVlsPa(U=%RAsXY>4IZFMg^8s#w4vzf9TH|Y@8`=a>v^y+nK6)e
z3X5DK829uoxlZA|xo!>!A!^rZ>zz^PJl0iKhN%N?x}dO+@pBX+rIe>#?#E7SrIdmb
zn89+1+SoH&GP^g_^-<wouI5B0o&Bs(f&`8LI~DiJXyyouj_~F39^vI(+`RNamW9(u
h+OArlA1^Dm{F1c_A67r#ST(oHtrQD~2QPc7><^w5Mt}eS

literal 0
HcmV?d00001

-- 
2.48.1

Re: [PATCH 5/7] doc: make pdfdocs: Update empty SVG file to something, otherwise compilation of the *.tex files fails

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 1342 bytes --]

On Mon, Aug 25, 2025 at 11:44:48PM +0100, Adriano Carvalho wrote:

> There is one SVG file (doc/develop/pics/spl_before_reloc.svg) that is empty (0-byte) and because of that it is not translated to PDF leading to an error. See below.
> This commit updates that file to something (i.e., an simple image with "TODO" written on it), solving the problem.
> 
> The error in docker.io/trini/u-boot-gitlab-ci-runner:jammy-20250714-25Jul2025:
> 
> uboot@35c89b9ab70e:~/u-boot$ make pdfdocs
> [...]
> WARNING: cannot copy image file '/home/uboot/u-boot/doc/output/.doctrees/images/spl_before_reloc.pdf': /home/uboot/u-boot/doc/output/.doctrees/images/spl_before_reloc.pdf does not exist
> [...]
> build finished with problems, 1 warning (with warnings treated as errors).
> make[1]: *** [doc/Makefile:84: latexdocs] Error 1
> make: *** [Makefile:2686: pdfdocs] Error 2
> 
> NOTE: This won't completely fix the pdfdocs target. See next commit(s).
> 
> Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
> ---
>  doc/develop/pics/spl_before_reloc.svg | Bin 0 -> 239 bytes
>  1 file changed, 0 insertions(+), 0 deletions(-)

It's not supposed to be zero byte I assume, so can we please figure out
what patch was misapplied (I have some ideas) and then find the version
where we get the right SVG? Thanks.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 5/7] doc: make pdfdocs: Update empty SVG file to something, otherwise compilation of the *.tex files fails

[Adriano Carvalho]

On Mon, 25 Aug 2025 at 23:58, Tom Rini <trini@konsulko.com> wrote:
> [...]
> It's not supposed to be zero byte I assume, so can we please figure out
> what patch was misapplied (I have some ideas) and then find the version
> where we get the right SVG? Thanks.
>
> --
> Tom

The problem seems to be with this patch:
https://patchwork.ozlabs.org/project/uboot/patch/20250319140327.301266-3-n-francis@ti.com/

The last part was cut-off even though there was something in there:

>  doc/develop/pics/spl_before_reloc.svg | Bin 0 -> 224608 bytes

I hope Neha still has the original.

I think this also got accepted by mistake:

> diff --git a/.gitattributes b/.gitattributes
> index 7a7c4163560..735b13da278 100644
> --- a/.gitattributes
> +++ b/.gitattributes
> @@ -6,3 +6,4 @@
>  *.ttf binary
>  *.gz binary
>  *.png binary
> +*.svg binary

Com os melhores cumprimentos. / Best regards.
Adriano Carvalho

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

[Adriano Carvalho]

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@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'
[...]

[340]

! LaTeX Error: Too deeply nested.

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

l.25503 \begin{itemize}

? Output written on board.pdf (344 pages).
Transcript written on board.log.
make[2]: *** [Makefile:29: board.pdf] Error 1
make[1]: *** [doc/Makefile:95: pdfdocs] Error 2
make: *** [Makefile:2686: 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@gmail.com>
---
 doc/build/documentation.rst | 4 +---
 doc/conf.py                 | 2 ++
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
index 1e97085fc89..bb13b8589b3 100644
--- a/doc/build/documentation.rst
+++ b/doc/build/documentation.rst
@@ -84,9 +84,7 @@ 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 43472d5dc3d..7b1a1a2a6a1 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -378,6 +378,8 @@ latex_elements = {
         \\setromanfont{DejaVu Serif}
         \\setmonofont{DejaVu Sans Mono}
      ''',
+
+     'maxlistdepth': 10, # Default is 6.
 }
 
 # At least one book (translations) may have Asian characters
-- 
2.48.1

[PATCH 7/7] doc: make pdfdocs: Remove redundant "-j" option

[Adriano Carvalho]

The "-j" option is specified twice which seems redundant.
sphinx-build's documentation doesn't mention the use of this options twice.
The "-j auto" version has been kept and the other version removed.

Signed-off-by: Adriano Carvalho <adrianocarvalho.pt@gmail.com>
---
 doc/Makefile | 1 -
 1 file changed, 1 deletion(-)

diff --git a/doc/Makefile b/doc/Makefile
index d0904a9f990..b37071b2803 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -56,7 +56,6 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 	PYTHONDONTWRITEBYTECODE=1 \
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
 	$(SPHINXBUILD) \
-	-j$(shell nproc) \
 	-b $2 \
 	-j auto \
 	-c $(abspath $(srctree)/$(src)) \
-- 
2.48.1