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 4D64EC53210 for ; Sun, 8 Jan 2023 15:06:10 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 656E185548; Sun, 8 Jan 2023 16:06:07 +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="PSir6U1i"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id A70E5855EA; Sun, 8 Jan 2023 16:06:05 +0100 (CET) Received: from mail-ej1-x62a.google.com (mail-ej1-x62a.google.com [IPv6:2a00:1450:4864:20::62a]) (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 2F78685254 for ; Sun, 8 Jan 2023 16:06:01 +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-ej1-x62a.google.com with SMTP id fc4so14213590ejc.12 for ; Sun, 08 Jan 2023 07:06:01 -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=wJsEvuQ+2IirpJeAKoNZ75tzCln63oYX38oRsud1dtc=; b=PSir6U1ih7I2uKp95EQX8LRU+bBPte+X3GpylrMGYDndftPVAIh9fkekWLZsGtT6pt +903iSjebje46neeSrH7cv4zFCPMqDl2tQz9dcEjgrRQm9HdM3dnT/I1RA8pttpPm8fj CQwyGawR/al8oYNiStitGJITFZ/VpQlL8Nn1k= 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=wJsEvuQ+2IirpJeAKoNZ75tzCln63oYX38oRsud1dtc=; b=3ix75jIIz4FD2bMpl7l/rNWuZF8N3BaPuVSpdPnDnxziZ2A03awL6v+7Dt53jAx4Ec D9HIXKmAIEu8vxh5yrLDOa4BsstzDqwzNJmtmYQQY4ip3NvRmnqsu/8yrIk6CSYDaWgm eTvzRNsmm9UQn5Figk719JL84ot01mwLDQ3V3CHBCh99qDhJUmNmtYYs2U+CkKyD8JWb TJtLwlKaGsrN+ewfO1vHMe1QsknhZu9jd0iWTvajnHp5qT+u3IlnG6TPN/lITUrAP/wA 4PCye5ZPlvg3QU6swK2Ka6Dm9A3qlws/HkHCpLiOLo9Tks3TDHdrQaBFI+lwydaE/MAZ odHg== X-Gm-Message-State: AFqh2koSNLDFkUmjoC1rtz85LLUXSXhJSj8tKoVD5g3GjZwm/B2i7uyO +LrshOyeukZN4P0uqaT1XeU93yRfV7bfDTj8uXn++Q== X-Google-Smtp-Source: AMrXdXtpsuTEtx9YQmXE+D0hoOX/00DbJDS19NP8L/ViWQHUTzHdqKIdANn/Os8UV/ScdEDJltbcRIlxmt3jCGZoSUs= X-Received: by 2002:a17:906:2857:b0:82d:1b76:1e44 with SMTP id s23-20020a170906285700b0082d1b761e44mr4618995ejc.93.1673190360477; Sun, 08 Jan 2023 07:06:00 -0800 (PST) MIME-Version: 1.0 References: <20221230181210.GE3787616@bill-the-cat> <7b000799-572b-2f20-4353-77d03b98d1ea@canonical.com> <2093f8dd-d8b7-cafc-857f-64a583ffed87@canonical.com> <7a2030a0-41be-8e95-f6b8-402ed26a99dc@canonical.com> <20230108134445.GZ3787616@bill-the-cat> In-Reply-To: <20230108134445.GZ3787616@bill-the-cat> From: Simon Glass Date: Sun, 8 Jan 2023 08:05:48 -0700 Message-ID: Subject: Re: [PATCH 1/1] doc: building documentation To: Tom Rini Cc: Heinrich Schuchardt , 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 Tom, On Sun, 8 Jan 2023 at 06:44, Tom Rini wrote: > > On Sat, Jan 07, 2023 at 07:37:03PM -0700, Simon Glass wrote: > > Hi Heinrich, > > > > On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt > > wrote: > > > > > > > > > > > > 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/ > > > > Strangely, for me, it looks like the second thing even without the > > environment. I have seen the first one though, but not for a while.I > > vaguely remember installing some style package? > > See, stuff like this is why the virtualenv is the default and a python > best practice. You don't have to guess why things randomly look > different than expected (or even more fun, unexpectedly work) because > everyone is on the same environment. Skipping virtualenv is a user > beware kind of thing and not what we want to encourage. Yes I do understand that. I have sent the review tag a while back. It's just that it is so broken. This is the sort of thing that gives Python a bad name...what is missing here that it shouldn't 'just work'? Is it some sort of version conflict? Regards, Simon