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