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 36C5EC46467 for ; Sat, 7 Jan 2023 22:16:50 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 5CE4985282; Sat, 7 Jan 2023 23:16:47 +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="XRqNGy8E"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 0348785355; Sat, 7 Jan 2023 23:16:45 +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 BAD3A851B5 for ; Sat, 7 Jan 2023 23:16:41 +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-wr1-f72.google.com (mail-wr1-f72.google.com [209.85.221.72]) (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 3ABF83F5D2 for ; Sat, 7 Jan 2023 22:16:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=canonical.com; s=20210705; t=1673129801; bh=jbdtbR+T0FeZ8/I1bz7Yx/kj5xCRJ4Jddngjjua5FxY=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=XRqNGy8EDlVfpP3fw2cfgaCQoftUAvvL/yyUcV7r9+bjMM113EDZjK4WqLiDF0KT9 5DdoJiTuDMbxuTPiWujxw4e0FP5HndHM+NEiN4eIFsktxPDsoJzeUIN0PZa3JMe9Y6 EIPm7zcXxdgCShRnefDiMIua4bnZn+xf5jRsXcbfMwdkkEys6aD7XDusV/+p/gfyD6 2v1aYCAAw/kqA3txjcoiov8MHvck8n7ttzEXUxcNnka9oLh7vn/WxlNre7qYijmM3p 94j5XFsmUk8nMljfLfWd5T9ct+BLIpeCXyGiXhA+E9Gya3QQB5FVNotUepztevitR/ uZvha3QCUwAeA== Received: by mail-wr1-f72.google.com with SMTP id o5-20020adfba05000000b0029064ccbe46so594907wrg.9 for ; Sat, 07 Jan 2023 14:16:41 -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:content-language :references:cc:to:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=jbdtbR+T0FeZ8/I1bz7Yx/kj5xCRJ4Jddngjjua5FxY=; b=wHL6iEmWmLGT/aNY6QrG9nsj5yeZ9AmbNt85kuPOd6s+Cwhizj7r7efDmH69eP+dOV itJtS/Otf7/5qCEq1LeRbC0qeRGjGhJSJtUCS0WvWrs6bu33NBpwjgTi4xhFQZOFJ2Z4 Xoy97dRMqEGWXA9AkuF1c4teot12hc0Cu3qqc0uI4EcwUeaseYjdV5+c/7Bz53C8Rmtd I8jgj12CxXdiGdmbKTJHZLv3xpe0OSJgziVjYoZ8VX84lsjW/P1tO8XtUwm+VAuPTKbM MAgYFRvNOdBSjQnIxVgsJJ6IQAN8p9woBtfGeXVs6jPvdq/XKDSPTi1bxMjDzAbtL+Yl WO7g== X-Gm-Message-State: AFqh2kroAuDpIYd6fLb0Wb4gMXxBOoq82ALmZiaW4+HbueMHoxjH4k7v e8/OfK+TBMY8J0ErjOm67/3xGpXNURPWsyjak8k9VyHsWvJTSO7AMY6zWV9/IN9HHRG42seIsiO VUIyFstj2iFmPK20KP3Xorwq5d6MhBww= X-Received: by 2002:a05:6000:1e19:b0:29e:81a5:7eca with SMTP id bj25-20020a0560001e1900b0029e81a57ecamr13399835wrb.8.1673129800382; Sat, 07 Jan 2023 14:16:40 -0800 (PST) X-Google-Smtp-Source: AMrXdXt3Kq40pmid76gndBZnlpKU1CCruS4EkPjNjEsp8YUx1wkDrb7qmthzU9mg0zSLlkWAFTU3mQ== X-Received: by 2002:a05:6000:1e19:b0:29e:81a5:7eca with SMTP id bj25-20020a0560001e1900b0029e81a57ecamr13399827wrb.8.1673129800065; Sat, 07 Jan 2023 14:16:40 -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 l13-20020adfe58d000000b00296730b5c3esm4737177wrm.102.2023.01.07.14.16.39 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 07 Jan 2023 14:16:39 -0800 (PST) Message-ID: <2093f8dd-d8b7-cafc-857f-64a583ffed87@canonical.com> Date: Sat, 7 Jan 2023 23:16:38 +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 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> Content-Language: en-US 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 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. Best regards Heinrich > > Would it be possible to have the virtual env start/stop stuff in a > separate place? I suppose that would not be ideal either, since it > would make the instructions more complicated for those that have > trouble... > > Reviewed-by: Simon Glass > > Regards, > Simon