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 15B29C54EBC for ; Sun, 8 Jan 2023 00:11:45 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 712D48533F; Sun, 8 Jan 2023 01:11:43 +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="jcwHca1L"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3D6D585369; Sun, 8 Jan 2023 01:11:42 +0100 (CET) Received: from smtp-relay-internal-0.canonical.com (smtp-relay-internal-0.canonical.com [185.125.188.122]) (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 DB6D785282 for ; Sun, 8 Jan 2023 01:11:37 +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 mail-wm1-f69.google.com (mail-wm1-f69.google.com [209.85.128.69]) (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-internal-0.canonical.com (Postfix) with ESMTPS id 7327C3F5CF for ; Sun, 8 Jan 2023 00:11:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=canonical.com; s=20210705; t=1673136697; bh=Wg+rk0fn7ay0JSanPD5lj1zPLff0TXiSYXh9WaJOPzA=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=jcwHca1LUFmCBTgWat/WXiIsTN6nm6AhBHlwg4t+YvIKqLkIzR7zsDYySAkrRUO/G Go0QNZEkzrVbKWZh5YrzT/LzlLEe6x9GGRcDfbIw1X+lswzdiuMMx7j4ESPgGpzNck XTBOf5Pz8/x26bUMraT8tMP2QJtb/g+u0/a5/IA4zBOrygGynObOkEqNu04DCDC8qP jHKRgZdW4bOliDBJLM1REZ954e3LQ3i0DqGdFENdnoP+kUjBj8WMIcafJLPvcqC98b DIpC/iTyZwR9dHgPeYksNOXZMy8CSN8EHGojMYpQM7jsXou9or0wGh/vGn9sWcOM98 PRYUhIR2ay17A== Received: by mail-wm1-f69.google.com with SMTP id m38-20020a05600c3b2600b003d1fc5f1f80so4933595wms.1 for ; Sat, 07 Jan 2023 16:11:37 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:in-reply-to:from:references:cc:to :content-language:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=Wg+rk0fn7ay0JSanPD5lj1zPLff0TXiSYXh9WaJOPzA=; b=2nDBri+2axiUnzmtmC4dJ0FM83D3bQDIFNpUU2HUniy0eCVzbScE07+PvIn14rPXFl bs1BMcykF+yjP1uobW/kAmqjPnNF+KiAkUiGm3+1L7+s75USeaNqgEnD5RVI8JmAbylJ sC7CTsLFIZ6Og94lHriQY9OP/rU7CyATubW5JZyP2kFkYizJ5Gy5QGgVnbgrqswjuRhF WQoSJDcY9MwpT+Ac8D22+rFbUGamI+B9CdEs7fCYaVpbbsAp4pVM+0RHvpxsXPHTWgHP eyayxH0lg+pad1cCyv+nQKmDyKwyPALyq+MMDf9e1nn8+yVEbsF12sUMnwF7QWhbrtn1 TwoQ== X-Gm-Message-State: AFqh2kps6UB5pwOt/myaosKgTm9iSrqjVuq5NmHc/alo0UB/cGyH0AVT 7LjRvH47qxmsqMB/qtwebd+qk9xHhej/BlteG2ORYgf3rLdbd3+ka01E1yvTXbfU7NXeI6jrGC1 +BxK8VUJAdsHPiMm0Stv88AyazW2l5QM= X-Received: by 2002:a05:600c:4999:b0:3d3:4007:9c88 with SMTP id h25-20020a05600c499900b003d340079c88mr44939827wmp.18.1673136697021; Sat, 07 Jan 2023 16:11:37 -0800 (PST) X-Google-Smtp-Source: AMrXdXs1OAlo06De24vie6UzVuOBw5aIANBUFoarivoHiAULk/xSSgMqpgijOytMZtJryZWJQXVtbw== X-Received: by 2002:a05:600c:4999:b0:3d3:4007:9c88 with SMTP id h25-20020a05600c499900b003d340079c88mr44939813wmp.18.1673136696699; Sat, 07 Jan 2023 16:11:36 -0800 (PST) Received: from [192.168.123.94] (ip-088-152-145-137.um26.pools.vodafone-ip.de. [88.152.145.137]) by smtp.gmail.com with ESMTPSA id bh13-20020a05600c3d0d00b003d358beab9dsm6565873wmb.47.2023.01.07.16.11.36 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 07 Jan 2023 16:11:36 -0800 (PST) Message-ID: <7a2030a0-41be-8e95-f6b8-402ed26a99dc@canonical.com> Date: Sun, 8 Jan 2023 01:11:35 +0100 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.6.0 Subject: Re: [PATCH 1/1] doc: building documentation Content-Language: en-US To: Simon Glass Cc: Tom Rini , Maxim Cournoyer , u-boot@lists.denx.de References: <20221230040745.16619-1-heinrich.schuchardt@canonical.com> <20221230181210.GE3787616@bill-the-cat> <7b000799-572b-2f20-4353-77d03b98d1ea@canonical.com> <2093f8dd-d8b7-cafc-857f-64a583ffed87@canonical.com> From: Heinrich Schuchardt In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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 On 1/7/23 23:54, Simon Glass wrote: > Hi Heinrich, > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt > wrote: >> >> >> >> On 1/7/23 19:55, Simon Glass wrote: >>> Hi Heinrich, >>> >>> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt >>> wrote: >>>> >>>> >>>> >>>> On 12/30/22 20:02, Simon Glass wrote: >>>>> Hi, >>>>> >>>>> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt >>>>> wrote: >>>>>> >>>>>> >>>>>> >>>>>> On 12/30/22 19:12, Tom Rini wrote: >>>>>>> On Fri, Dec 30, 2022 at 11:51:15AM -0600, Simon Glass wrote: >>>>>>>> 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 >>>>>>> >>>>>>> Which part, exactly? Using a virtual environment is I believe a normal >>>>>>> best practice and "python3 -m pip" rather than "pip3" I assume is >>>>>>> another best practice for portability. Then maybe the final step should >>>>>>> say "Review" not "Display" ? >>>>>>> >>>>>> >>>>>> Review only applies to documentation developers. >>>>>> Normal users just want to read the documentation. >>>>> >>>>> Using a virtual environment seems annoying to me. Should we put that >>>>> in a separate section for those who want to do it? >>>> >>>> Current Ubuntu packages are incompatible with the readthedocs theme. >>>> Therefore I describe a way of building that works for most users. >>> >>> OK I see. Somehow it builds OK for me on 22.04 but I have not tried >>> newer versions. >> >> make htmldocs builds but the formatting of the HTML does not conform to >> the readthedocs style. Just open the documentation in a browser. > > It looks OK for me...what should I be seeing? This is the output without Python environment: https://gist.github.com/xypron/aef88822a1f2f34e29faf5302313de6a This is what it should look like: https://u-boot.readthedocs.io/en/latest/ Best regards Heinrich