blob: 098c96a4c4ff9e77274e1083ef283687f45bd15e (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
.. 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://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:
.. 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*.
|
