jcs.org
"Das U-Boot" Source Tree
1.. SPDX-License-Identifier: GPL-2.0+:
2
3Building documentation
4======================
5
6The U-Boot documentation is based on the Sphinx documentation generator.
7
8In addition to the Python packages listed in ``doc/sphinx/requirements.txt``,
9the following dependencies are needed to build the documentation:
10
11* fontconfig
12
13* graphviz
14
15* imagemagick
16
17* texinfo (if building the `Infodoc documentation`_)
18
19HTML documentation
20------------------
21
22The *htmldocs* target is used to build the HTML documentation. It uses the
23`Read the Docs Sphinx theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_.
24
25.. code-block:: bash
26
27 # Create Python environment 'myenv'
28 python3 -m venv myenv
29 # Activate the Python environment
30 . myenv/bin/activate
31 # Install build requirements
32 python3 -m pip install -r doc/sphinx/requirements.txt
33 # Build the documentation
34 make htmldocs
35 # Deactivate the Python environment
36 deactivate
37 # Display the documentation in a graphical web browser
38 x-www-browser doc/output/index.html
39
40The HTML documentation is published at https://docs.u-boot.org. The build
41process for that site is controlled by the file *.readthedocs.yml*.
42
43Infodoc documentation
44---------------------
45
46The *infodocs* target builds both a texinfo and an info file:
47
48.. code-block:: bash
49
50 # Create Python environment 'myenv'
51 python3 -m venv myenv
52 # Activate the Python environment
53 . myenv/bin/activate
54 # Install build requirements
55 python3 -m pip install -r doc/sphinx/requirements.txt
56 # Build the documentation
57 make infodocs
58 # Deactivate the Python environment
59 deactivate
60 # Display the documentation
61 info doc/output/texinfo/u-boot.info
62
63PDF documentation
64-----------------
65
66The *pdfdocs* target is meant to be used to build PDF documenation.
67As v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
68
69We can use texi2pdf instead:
70
71.. code-block:: bash
72
73 # Create Python environment 'myenv'
74 python3 -m venv myenv
75 # Activate the Python environment
76 . myenv/bin/activate
77 # Install build requirements
78 python3 -m pip install -r doc/sphinx/requirements.txt
79 # Build the documentation
80 make texinfodocs
81 # Deactivate the Python environment
82 deactivate
83 # Convert to PDF
84 texi2pdf doc/output/texinfo/u-boot.texi
85
86Texinfo documentation
87---------------------
88
89To build only the texinfo documentation the *texinfodocs* target is used:
90
91.. code-block:: bash
92
93 # Create Python environment 'myenv'
94 python3 -m venv myenv
95 # Activate the Python environment
96 . myenv/bin/activate
97 # Install build requirements
98 python3 -m pip install -r doc/sphinx/requirements.txt
99 # Build the documentation
100 make texinfodocs
101 # Deactivate the Python environment
102 deactivate
103
104The output is in file *doc/output/texinfo/u-boot.texi*.