Open Menu / doc / build / documentation.rst
Loading...
 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
.. 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*.