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 8BAEDC54EBC for ; Sat, 7 Jan 2023 19:09:53 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id D59E985377; Sat, 7 Jan 2023 20:09:50 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com 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=konsulko.com header.i=@konsulko.com header.b="HyPD8KMz"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 37BB985494; Sat, 7 Jan 2023 20:09:49 +0100 (CET) Received: from mail-qt1-x82c.google.com (mail-qt1-x82c.google.com [IPv6:2607:f8b0:4864:20::82c]) (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 4BBD68533F for ; Sat, 7 Jan 2023 20:09:45 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=konsulko.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=trini@konsulko.com Received: by mail-qt1-x82c.google.com with SMTP id bp44so4993466qtb.0 for ; Sat, 07 Jan 2023 11:09:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=konsulko.com; s=google; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=jNGSTA1HjU0//BWCrF/3xN57owEhY/fgU8wxAs1mTEU=; b=HyPD8KMzha3rB7CJH9eeGF5hY5GZoTAPSY3qD2Amy4wIaAiWCVYihicFNTFrr1leox I5edEJe+MQrFzHpmsDwb4+VbEF6mInLHHG8t11a0EQZzurPMA7++AW19AxIbvVySjSK/ zRwwkp7MjrSHIpYXDknaWjiuBvZ/iMwiZ4+JM= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=jNGSTA1HjU0//BWCrF/3xN57owEhY/fgU8wxAs1mTEU=; b=6p98sfl3izlMjltKk8uW1d08KJ9PaAYOggWPtkd9cpbz+qrmZ1Wno4ysB3ELm2y5JB w1TBXxTpWTr0l6sKY36I8l5LMUqGdOQzFpZ+Me0p5oczd157tMOP6beNffCw/YCgHVqA +oVXsP0LlFBsD8b+LdD8p931Ze7Fpq9sZpnGjdjhwMwGrD5paFcUyQ7Ioz3FxA//VLkl nmAUgL3nz7anZ27Tu9bhKU6Iu9TJOJju66SfZ8brQ3EHJdgG3AJJ/tuRoQ5C8ngP2+3F VNJfP+hBIi4gU3Ou1qX872HuodnROP7wQazdLosxZKnyjxp3agLnw6SNu+qST1jUbiIH W3nQ== X-Gm-Message-State: AFqh2kqNVWhYUjQOhQqdoG/7BO9B24hdlsyl5xgwoParZXJ8kGNtXAS2 JDxrv5UpYMCGGktNKrIf/e3ylg== X-Google-Smtp-Source: AMrXdXvz3puUs3qMmXf5XTmSuUyagkNMXlGPnSDwwUNFNvpoLZHGELLygIgkh4TdBbRbnfIktD2+Bg== X-Received: by 2002:a05:622a:1741:b0:3a8:2716:ac2d with SMTP id l1-20020a05622a174100b003a82716ac2dmr115524813qtk.56.1673118584067; Sat, 07 Jan 2023 11:09:44 -0800 (PST) Received: from bill-the-cat (2603-6081-7b00-6400-64a1-0c30-ebd7-ca7b.res6.spectrum.com. [2603:6081:7b00:6400:64a1:c30:ebd7:ca7b]) by smtp.gmail.com with ESMTPSA id o24-20020a05620a229800b006fec1c0754csm2533274qkh.87.2023.01.07.11.09.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 07 Jan 2023 11:09:43 -0800 (PST) Date: Sat, 7 Jan 2023 14:09:41 -0500 From: Tom Rini To: Simon Glass Cc: Heinrich Schuchardt , Maxim Cournoyer , u-boot@lists.denx.de Subject: Re: [PATCH 1/1] doc: building documentation Message-ID: <20230107190941.GS3787616@bill-the-cat> References: <20221230040745.16619-1-heinrich.schuchardt@canonical.com> <20221230181210.GE3787616@bill-the-cat> <7b000799-572b-2f20-4353-77d03b98d1ea@canonical.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="2FYqgcQ35GOHRE7S" Content-Disposition: inline In-Reply-To: X-Clacks-Overhead: GNU Terry Pratchett 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 --2FYqgcQ35GOHRE7S Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Jan 07, 2023 at 11:55:59AM -0700, Simon Glass wrote: > Hi Heinrich, >=20 > 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 documentati= on. > > >>>>> > > >>>>> 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/documentatio= n.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 > > >>>>> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D > > >>>>> + > > >>>>> +The U-Boot documentation is based on the Sphinx documentation ge= nerator. > > >>>>> + > > >>>>> +HTML documentation > > >>>>> +------------------ > > >>>>> + > > >>>>> +The *htmldocs* target is used to build the HTML documentation. I= t 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 Pytho= n. I > > >>>> would use: > > >>>> > > >>>> pip3 install -r doc/sphinx/requirements.txt > > >>>> make htmldocs > > >>> > > >>> Which part, exactly? Using a virtual environment is I believe a nor= mal > > >>> best practice and "python3 -m pip" rather than "pip3" I assume is > > >>> another best practice for portability. Then maybe the final step sh= ould > > >>> 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. >=20 > OK I see. Somehow it builds OK for me on 22.04 but I have not tried > newer versions. >=20 > 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... As virtualenv is a python best practice, I believe we should just assume that users that want to skip it, know how to skip it. --=20 Tom --2FYqgcQ35GOHRE7S Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmO5w24ACgkQFHw5/5Y0 tyy9Wwv/SPKCwPaLpBXpHCpoTL3UU+sZ57Dxzm2I4tjh7UKAKkrU7eVgcyLsSukC HJeK0bh1fpH+4r/zKdd+XQCN+hNkPipJnIvWp9m30kaS5eMr6bQ70fSMj9Q7to16 YEZumKRgatg9usDEWb2eU3gBcehguLVDTIt8xtjd4P2LQmKo2QNPKFEu+7LymPrM c/Uhm8LqrNACbHM6MbTF5slgxQ4RTHbtm62LQXee3sSwm12uIq7VCeQSxn2FL5sM nqV3uw/RkpsjIzrDi8f8FPN76te6IdOyMmBWwQI4WkE0Z02fBD85kcOe1hPUT4t0 r3gYNRl1Aj4vITIpC2UHEt5kGSHcHj3EZU9rovzZOPCYJxHY7SrHuG1SbQaVOk0D O0LdKyoL80UrixZvdlgvmRpTQihpXzRBe8bEyXkg+/aSmr6j8XiAutkb/+CAqvAe so7HSn0t027J/B3eCgaUDUT6iw+2FqgU/U5EuO+LOjH5r7VwFWczQPoNrCP7PCUC ggXBhQS4 =bHcJ -----END PGP SIGNATURE----- --2FYqgcQ35GOHRE7S--