Building documentation

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

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 -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 htmldocs
# Deactivate the Python environment
deactivate
# Display the documentation in a graphical web browser
x-www-browser doc/output/index.html

Infodoc documentation

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

# 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 infodocs
# Deactivate the Python environment
deactivate
# Display the documentation
info doc/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 -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 texinfodocs
# Deactivate the Python environment
deactivate
# Convert to PDF
texi2pdf doc/output/texinfo/u-boot.texi

Texinfo documentation

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

# 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 texinfodocs
# Deactivate the Python environment
deactivate

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