doc: building documentation

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

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

2 files changed, 91 insertions, 0 deletions

diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
new file mode 100644
index 0000000..896264d
--- /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 9a8105d..dc9cde4 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -12,3 +12,4 @@ Build U-Boot
    docker
    tools
    buildman
+   documentation