From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 4C744C4332F for ; Fri, 30 Dec 2022 04:08:02 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B40F985165; Fri, 30 Dec 2022 05:07:59 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=canonical.com header.i=@canonical.com header.b="pjwiyYXJ"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id E08678516A; Fri, 30 Dec 2022 05:07:57 +0100 (CET) Received: from smtp-relay-canonical-1.canonical.com (smtp-relay-canonical-1.canonical.com [185.125.188.121]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 8DEC48512B for ; Fri, 30 Dec 2022 05:07:54 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=canonical.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=heinrich.schuchardt@canonical.com Received: from LT2ubnt.fritz.box (ip-088-152-145-137.um26.pools.vodafone-ip.de [88.152.145.137]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp-relay-canonical-1.canonical.com (Postfix) with ESMTPSA id B0B634358C; Fri, 30 Dec 2022 04:07:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=canonical.com; s=20210705; t=1672373273; bh=eJoIyQfYn1/1PVSrQCBGI2cDdD9ES9C7tU7zg0e/hzI=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=pjwiyYXJ2foFg6OG+J/AoD2uYuM9fTfd2SJbefRK71vM6S/AotuBmXA/fvJqIWCUq aijrLXZ6DQDiXIxrY5w1e16W3A1oAfxOhzRXPyEpQ6OzI61+Y5iYJPp1NYxynHHF/A f0mlzhvIUOtQIovzV8sgEJD9BXCTtGCGBhgEwKOQIZm7VtvmhQnHMraTHBTKXuTXcs msR3WOJYZIVnxnb7ofMvuihiFX6tFMPpXYLrEfc61qBNACokFxEH+a83En2AguFfLq xGX7cv/xae0x8ZJowmDmH5XLg9RRyL2yLLXRLq5TxS00MwAo/tn8FMBuAFpdcK5dTn CcgJcmj/zOkFw== From: Heinrich Schuchardt To: Tom Rini Cc: Maxim Cournoyer , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH 1/1] doc: building documentation Date: Fri, 30 Dec 2022 05:07:45 +0100 Message-Id: <20221230040745.16619-1-heinrich.schuchardt@canonical.com> X-Mailer: git-send-email 2.37.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean 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 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 `_. + +.. 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 -- 2.37.2