mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-25 12:33:41 +00:00
2a3c0680e6
Highlight the packages which need to be installed in order to build the docs. Signed-off-by: Paul Barker <paul.barker.ct@bp.renesas.com>
104 lines
2.8 KiB
ReStructuredText
104 lines
2.8 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+:
|
|
|
|
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 <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
|
|
|
|
The HTML documentation is published at https://u-boot.readthedocs.io. 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:
|
|
|
|
.. 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*.
|