Building documentation

The U-Boot documentation is based on the Sphinx documentation generator.

In addition to the Python packages listed in doc/sphinx/requirements.txt, the following dependencies are needed to build the documentation:

fontconfig
graphviz
imagemagick
texinfo (if building the Infodoc documentation)

HTML documentation

The htmldocs target is used to build the HTML documentation. It uses the Read the Docs Sphinx theme.

# Create Python environment 'myenv'
python3-mvenvmyenv
# Activate the Python environment
.myenv/bin/activate
# Install build requirements
python3-mpipinstall-rdoc/sphinx/requirements.txt
# Build the documentation
makehtmldocs
# Deactivate the Python environment
deactivate
# Display the documentation in a graphical web browser
x-www-browserdoc/output/index.html

The HTML documentation is published at https://docs.u-boot.org. The build process for that site is controlled by the file .readthedocs.yml.

Infodoc documentation

The infodocs target builds both a texinfo and an info file:

# Create Python environment 'myenv'
python3-mvenvmyenv
# Activate the Python environment
.myenv/bin/activate
# Install build requirements
python3-mpipinstall-rdoc/sphinx/requirements.txt
# Build the documentation
makeinfodocs
# Deactivate the Python environment
deactivate
# Display the documentation
infodoc/output/texinfo/u-boot.info

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

We can use texi2pdf instead:

# Create Python environment 'myenv'
python3-mvenvmyenv
# Activate the Python environment
.myenv/bin/activate
# Install build requirements
python3-mpipinstall-rdoc/sphinx/requirements.txt
# Build the documentation
maketexinfodocs
# Deactivate the Python environment
deactivate
# Convert to PDF
texi2pdfdoc/output/texinfo/u-boot.texi

Texinfo documentation

To build only the texinfo documentation the texinfodocs target is used:

# Create Python environment 'myenv'
python3-mvenvmyenv
# Activate the Python environment
.myenv/bin/activate
# Install build requirements
python3-mpipinstall-rdoc/sphinx/requirements.txt
# Build the documentation
maketexinfodocs
# Deactivate the Python environment
deactivate

The output is in file doc/output/texinfo/u-boot.texi.