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 B6E66C4167B for ; Fri, 30 Dec 2022 17:52:27 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 2516385553; Fri, 30 Dec 2022 18:51:54 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="A33UK7oM"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id BEFDD85536; Fri, 30 Dec 2022 18:51:33 +0100 (CET) Received: from mail-ed1-x530.google.com (mail-ed1-x530.google.com [IPv6:2a00:1450:4864:20::530]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 67DF785543 for ; Fri, 30 Dec 2022 18:51:28 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@google.com Received: by mail-ed1-x530.google.com with SMTP id b88so24024434edf.6 for ; Fri, 30 Dec 2022 09:51:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=J3+IRDgj15kE62i5Ev9TpgK6wko36vDZ2CjaZtxd++0=; b=A33UK7oMp8+igxYFGlzkWIygsf4yoiFmWwEOuDt3d01+io16TDXsLXjlyrm0Vb/qHz v8SJ0KmZdFUW2y+TGgvv5iBYw2ljCskRzpCFiKR1yRCd2FdaQlOuoV5PMyBCzY7SzdsV RBD3p7Esawe6Hmai0N4lVc0fUEOADRH8lEEVA= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=J3+IRDgj15kE62i5Ev9TpgK6wko36vDZ2CjaZtxd++0=; b=hD4NF5YncvjKdrXB0DwRQitXjn2JJdkAShLOGACf5PQQSrKfRDoLaOfAH9uVixTG23 qP0cNa5IBdz1w7bVWeJqJbP2DiBn1RRLJvL1kvMoQ1KsOS8MQevaSYn0XSnhyI/iaLJ/ LEON1xuuBcYx6UT8uLjzSvPNsAIa5qRpH4u1Xe7zET2pgSR6X3fsvHgnY4EfWXZEfeKP iGV+RGiowP5brax8fbrjcz/JrpUvLih4MGcX8GotzqtHP92WO/h0kMXKuY7OZrI2eXkG sIVpT3BjqCva3+echD9MbQK82FDJtxD5NOUktmrbPoA8t8S3FK7MOX5dPMYe7rANXMQD 7vsg== X-Gm-Message-State: AFqh2kosmF5c1GoOHDKZPad8gkSJcRuil1f3FiUCDygpsK5m2bhs4W1l mpcRCzRwNZCXUXz0a9A9RE1f77f8fKjSR+TdrwGGLg== X-Google-Smtp-Source: AMrXdXvk0xIYw7Yov6/MX3MqLRFPZvRk7GfhfsfSgHaEys/xOmTw325c+/5HeyeV0ecDYQsBnM2ZEq7ka6MuSU53yxo= X-Received: by 2002:a05:6402:298b:b0:47f:7465:6e76 with SMTP id eq11-20020a056402298b00b0047f74656e76mr2734617edb.181.1672422687743; Fri, 30 Dec 2022 09:51:27 -0800 (PST) MIME-Version: 1.0 References: <20221230040745.16619-1-heinrich.schuchardt@canonical.com> In-Reply-To: <20221230040745.16619-1-heinrich.schuchardt@canonical.com> From: Simon Glass Date: Fri, 30 Dec 2022 11:51:15 -0600 Message-ID: Subject: Re: [PATCH 1/1] doc: building documentation To: Heinrich Schuchardt Cc: Tom Rini , Maxim Cournoyer , u-boot@lists.denx.de Content-Type: text/plain; charset="UTF-8" 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 Hi Heinrich, On Thu, 29 Dec 2022 at 22:08, Heinrich Schuchardt wrote: > > 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 If this is necessary then it is a bit of a sad indictment on Python. I would use: pip3 install -r doc/sphinx/requirements.txt make htmldocs > + > +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 > Regards, Simon