From: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
Date: Fri, 30 Dec 2022 04:05:31 +0000 (+0100)
Subject: doc: building documentation
X-Git-Tag: v2025.01-rc5-pxa1908~1167^2~7
X-Git-Url: http://git.dujemihanovic.xyz/html/static/gitweb.css?a=commitdiff_plain;h=566b7b2f518797540413bf55862b6562158aced9;p=u-boot.git

doc: building documentation

Provide a man-page describing how to build the U-Boot documentation.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
---

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
new file mode 100644
index 0000000000..896264dd7c
--- /dev/null
+++ b/doc/build/documentation.rst
@@ -0,0 +1,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*.
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 9a8105db21..dc9cde4001 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -12,3 +12,4 @@ Build U-Boot
    docker
    tools
    buildman
+   documentation