From 566b7b2f518797540413bf55862b6562158aced9 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 30 Dec 2022 05:05:31 +0100 Subject: [PATCH] doc: building documentation Provide a man-page describing how to build the U-Boot documentation. Signed-off-by: Heinrich Schuchardt --- doc/build/documentation.rst | 90 +++++++++++++++++++++++++++++++++++++++++++++ doc/build/index.rst | 1 + 2 files changed, 91 insertions(+) create mode 100644 doc/build/documentation.rst 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 `_. + +.. 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 -- 2.7.4