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 24DD2C46467 for ; Sat, 7 Jan 2023 22:55:04 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B5A3885369; Sat, 7 Jan 2023 23:55: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=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="N4UP7j3Y"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 6D2F58545F; Sat, 7 Jan 2023 23:54:59 +0100 (CET) Received: from mail-ed1-x534.google.com (mail-ed1-x534.google.com [IPv6:2a00:1450:4864:20::534]) (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 DE3EB85215 for ; Sat, 7 Jan 2023 23:54: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=sjg@google.com Received: by mail-ed1-x534.google.com with SMTP id s5so7139023edc.12 for ; Sat, 07 Jan 2023 14:54:54 -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=1jlUebr71d8RmloJC8cBjPDSR/zDnihOcff40OBcKsk=; b=N4UP7j3YB1yvcnyZrDanxwAoBlbmx8NNHwBu1TxHt7X6ZURDjXEB2pT2aXrQ0QZzbT 8BsJt4srx2XVy66CNDe1n/HLR6hah2HGdI5lywwu2B8Xv0Id9Ud/Nyj+euEq6QMLD9rL ZfjuVFbY4No7yF15sIjplYKatBA0N3gpYFBgI= 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=1jlUebr71d8RmloJC8cBjPDSR/zDnihOcff40OBcKsk=; b=rH/WxL9Mhy4i08wrV/PdjFJoeBt9Q9lvGapeIAujLXTNHo1pw+2KbjMuE2TlPp/4Zi IwA6BEuusvmjqYTwgw7bKW7LsToTzvrJswezXYLF/nr5/JCnecO34x7kC8o0vUzGQAhs UsOOpALB9ePswC5zS+VohqEpr3De/Uhi2oDYyZyDGViubVFv/WYhtV61qm5F1X956fpV EDG5jgTs9SFxrca/9pgV/129o5YDPtVrk2dP1l1/LgCfaL83AgXipwmhmeDpFtCm1vem TuLgqOgLNmiKAD5mym0QxJ6nnoiEVuC0t2XXosr3x/vbvG4z89MOoSM/2qFVbRosU5Jl yeoQ== X-Gm-Message-State: AFqh2kpqb/NmXOlhylYWpoEUwV8KHw8d8defv7Ursayl3lF8dV9rnE2N +tqqWDm41OnCJEcyZp8QoFHYsRef/MpEOjO/RumGEA== X-Google-Smtp-Source: AMrXdXsBv6jjyqZyOloTK5l0Sm7Aon7s2PVX9w5lk7N2ZweUJse/7wOk4SRjCR/rnXIvVxwA2BgMH9B3hfmYq1Y6Ddk= X-Received: by 2002:a05:6402:4c6:b0:478:f729:3008 with SMTP id n6-20020a05640204c600b00478f7293008mr5744926edw.281.1673132094231; Sat, 07 Jan 2023 14:54:54 -0800 (PST) MIME-Version: 1.0 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> In-Reply-To: <2093f8dd-d8b7-cafc-857f-64a583ffed87@canonical.com> From: Simon Glass Date: Sat, 7 Jan 2023 15:54:42 -0700 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 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? Regards, Simon