91 lines
2.4 KiB
ReStructuredText
91 lines
2.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+:
|
|
|
|
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 <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_.
|
|
|
|
.. 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 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:
|
|
|
|
.. 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 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:
|
|
|
|
.. 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 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:
|
|
|
|
.. 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 texinfodocs
|
|
# Deactivate the Python environment
|
|
deactivate
|
|
|
|
The output is in file *doc/output/texinfo/u-boot.texi*.
|