u-boot/doc/build/documentation.rst

91 lines
2.4 KiB
ReStructuredText
Raw Normal View History

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