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 93422C54EBD for ; Sun, 8 Jan 2023 13:44:56 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 379F885254; Sun, 8 Jan 2023 14:44:54 +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="agxAUcTg"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 71B33852D3; Sun, 8 Jan 2023 14:44:52 +0100 (CET) Received: from mail-qt1-x835.google.com (mail-qt1-x835.google.com [IPv6:2607:f8b0:4864:20::835]) (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 0879F851D3 for ; Sun, 8 Jan 2023 14:44:49 +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-x835.google.com with SMTP id z12so5900811qtv.5 for ; Sun, 08 Jan 2023 05:44:48 -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=uQ+pUTpqQgnJ/XkeRu6qre7JoX+ztqoSobyXXgbZMsI=; b=agxAUcTgcfXf+oJTe7mFHeDmbdqTJ+SvLdrcxvYX2y1rWi0DnEciSn+iMh9P8RpiIZ Bz4kLx/PzAikd/Tw0R6+L6FeXJuVB/88aVYRTYXn05nAlPFv0T0zXp2g5wPORs0TKQLE RuMPzqwPhNSiiSl7aCObkwmUrANQbR+v+KwcQ= 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=uQ+pUTpqQgnJ/XkeRu6qre7JoX+ztqoSobyXXgbZMsI=; b=xgPDy7Vz8VumJSTo9YWd8fBZ1m+2iZYou71pz3N1ut9Qga1AopFaPSOzapR+uvXQGP zIE8zaYFsERHH80swIOBU8keF2FbqETRcrSWSrJbF045ucdCZofnpzPSeCVbo8I4J/U0 J86bX4KrjTPOXHvlQV83RYaEI1xC/QOpZS9P9Ajds1kUodiPK6klW3nohpIl2WhJ4Wkt ag80dmflaIzsbNZeP4ChvB0rIqFvsb6bttvlo+qhTcv1iuE4t8GBAH3pYYWH5e8Zuuli IvDmqR0NfxB24N2P1sp3kd2It8MAmB10bIBj4Zcgg8K+HNLz9hboC4qgYl2qC1moSYpp Wb3Q== X-Gm-Message-State: AFqh2koi1nIPh2vR5Einz14UjOIOPgrzWGGRYflU3G/afa1Ac/elrbzF F4LGGIvCCK4VktRE2G39lycO5DnlxLbDPT1EgT8= X-Google-Smtp-Source: AMrXdXsetjJRt6q4fveKx05VJ2y4//VeOyOjBiHQCy6uCQp4fc0L5jTqhxCs4CQ+gfo6GH1o0d35/g== X-Received: by 2002:a05:622a:4188:b0:3a7:e4ae:7937 with SMTP id cd8-20020a05622a418800b003a7e4ae7937mr89347428qtb.6.1673185487781; Sun, 08 Jan 2023 05:44:47 -0800 (PST) Received: from bill-the-cat (2603-6081-7b00-6400-a51c-8a60-c39b-2d7f.res6.spectrum.com. [2603:6081:7b00:6400:a51c:8a60:c39b:2d7f]) by smtp.gmail.com with ESMTPSA id bs13-20020a05620a470d00b006b95b0a714esm3663079qkb.17.2023.01.08.05.44.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 08 Jan 2023 05:44:47 -0800 (PST) Date: Sun, 8 Jan 2023 08:44:45 -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: <20230108134445.GZ3787616@bill-the-cat> 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> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="G6cSxeHK+wgosN6N" 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 --G6cSxeHK+wgosN6N Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Jan 07, 2023 at 07:37:03PM -0700, Simon Glass wrote: > Hi Heinrich, >=20 > 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 documen= tation. > > >>>>>>>>> > > >>>>>>>>> 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/document= ation.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 documentatio= n generator. > > >>>>>>>>> + > > >>>>>>>>> +HTML documentation > > >>>>>>>>> +------------------ > > >>>>>>>>> + > > >>>>>>>>> +The *htmldocs* target is used to build the HTML documentatio= n. 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 P= ython. 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 ste= p 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 t= hat > > >>>>> in a separate section for those who want to do it? > > >>>> > > >>>> Current Ubuntu packages are incompatible with the readthedocs them= e. > > >>>> 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/ >=20 > 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. --=20 Tom --G6cSxeHK+wgosN6N Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGzBAABCgAdFiEEGjx/cOCPqxcHgJu/FHw5/5Y0tywFAmO6yM0ACgkQFHw5/5Y0 tywJ3gv9HbT6M6Y7uU9+NXadzhHYvYs0OJOkZs381qR1SlMu2i9rh0/WOzHpunHf WAyOvaBN5U9+xu5CPy1ac6PTr/FJL4W1lBYGfTP21jOuETEPpyXjgVg8yJDHT3Jf B+hpYjHlhEOYX7/7/E8svao0AO2tM7HXE3NKuaixJ2tSz3hsp9+oWp0t/hoxamHI nB/rsOBfT5Y/SPjJ5dGp74jKNbfK4jI05amQo0abDArGGyWN1+fsA6TKaeayw9xq UnVVtytLs95tvj2dRglgUPBrtbQdXK/amfpSODANRhOwbEDMCJIlh/N51y6v87iu rF8U1e5I+uQme9iSkRrtNzIfUTBkMvUJOXAU1Xk98hqgwB5yA2ywbC2CUlNCwRSd CObOoJO+rePaQXmEFMCDRkm1nzLqJ4wL+cTzzo13TLRDNlsZDwcm5J2HNDcmH/l/ vN5ZKa6i0Z0hnyKp0qJjVTj7t1SJ0IV+XMhNEyhHt62yAPwFjPss5VXVrAAAWD2H MONfW7VS =QiRU -----END PGP SIGNATURE----- --G6cSxeHK+wgosN6N--