From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id BFB1D4571A; Fri, 2 Aug 2024 15:53:10 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 9147941141; Fri, 2 Aug 2024 15:53:10 +0200 (CEST) Received: from fout6-smtp.messagingengine.com (fout6-smtp.messagingengine.com [103.168.172.149]) by mails.dpdk.org (Postfix) with ESMTP id 77B8F40E20 for ; Fri, 2 Aug 2024 15:53:09 +0200 (CEST) Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailfout.nyi.internal (Postfix) with ESMTP id 24FD0138543E; Fri, 2 Aug 2024 09:53:09 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute5.internal (MEProxy); Fri, 02 Aug 2024 09:53:09 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= cc:cc:content-transfer-encoding:content-type:content-type:date :date:from:from:in-reply-to:in-reply-to:message-id:mime-version :references:reply-to:subject:subject:to:to; s=fm3; t=1722606789; x=1722693189; bh=HmUdA22vrRahvOve5tcOUlX2sOYjhL8GUfxwF/Mt4k8=; b= UWdO80Tr9uhLLCa+m3hLK1Z7MxLwRsaaryRHigVw+LlHOgaUQ6Q5+/tATlBg094O LCNKqllpxCZMMxTRW9LnoODf988ugHSAWA4R9E9PtgqB3vce5H4+Ju6GvQsCgLrN tlXFYpWE7SvBAKZ9HQkCbHGJCCTtZ9gTxiGy5QhVCDglmQkmaGJJdMJcyLCB+Lku YUwHQ2F6Sw+UTS7yFANTrmo98/VpTG2I5TWGkHWL0PP75ENWA1zQa2klnswoqbdT 56DsgEs3LFJSAmG2yzvaFlewsqfTRkREcJ38TSKOO8hURU1hIkDP3jgj7XiIqumy Ng8KNW6pI0jlW6ATMKhr4A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-transfer-encoding :content-type:content-type:date:date:feedback-id:feedback-id :from:from:in-reply-to:in-reply-to:message-id:mime-version :references:reply-to:subject:subject:to:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t=1722606789; x= 1722693189; bh=HmUdA22vrRahvOve5tcOUlX2sOYjhL8GUfxwF/Mt4k8=; b=b YMXVrEy0SS7OsuBazooQ2CBgONWUCUB5cKvAWiYD7colD+H6eJPOsVVwcpzFmKw+ XPKpBF/aoPn5VCeNxwvhqFiCZJSDjXd2jvnWY1cguYHtcDowypJECqDf7hPajUvx ZMPJDzhwWEFomlr3nfAWISH0UpkL9PRx1HAVKPsBIjA7lKZFMXGAo0SAoJQaOl2J pd7HxvOR+BzbVFO4UHvIhAui1QbbXSE6lCsg3aSs8ZTZsCSerf+qU8bCLUChfEeZ IxL2jq/roU9e78gRO+WD0f3lb0GgtXC5Ih4Jd2VZ1OaAwfvv7SdRLVT+xXny5a35 /xgeJLbvrugtpJ3gEC1vg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrkedtgdeilecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhvfevufffkfgjfhgggfgtsehtqhertddttdejnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepgedttdeljeejgeffkeekkedtjeevtdehvedtkeeivdeuuedviedu vdelveejueejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh homhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvthdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i47234305:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Fri, 2 Aug 2024 09:53:07 -0400 (EDT) From: Thomas Monjalon To: Juraj =?utf-8?B?TGlua2XFoQ==?= Cc: Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, dev@dpdk.org Subject: Re: [PATCH v8 5/5] dts: add API doc generation Date: Fri, 02 Aug 2024 15:53:06 +0200 Message-ID: <1801384.VLH7GnMWUR@thomas> In-Reply-To: <5322c7b0-4935-439b-b8d5-a11bdac15150@pantheon.tech> References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <2336017.ElGaqSPkdT@thomas> <5322c7b0-4935-439b-b8d5-a11bdac15150@pantheon.tech> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org 02=C3=A9 x/08/2024 12:48, Juraj Linke=C5=A1: > On 1. 8. 2024 17:07, Thomas Monjalon wrote: > > 01/08/2024 15:03, Juraj Linke=C5=A1: > >> On 30. 7. 2024 15:51, Thomas Monjalon wrote: > >>> 12/07/2024 10:57, Juraj Linke=C5=A1: > >>>> +dts_root =3D environ.get('DTS_ROOT') > >>> > >>> Why does it need to be passed as an environment variable? > >>> Isn't it a fixed absolute path? > >> > >> The path to DTS needs to be passed in some way (and added to sys.path) > >> so that Sphinx knows where the sources are in order to import them. > >> > >> Do you want us to not pass the path, but just hardcode it here? I didn= 't > >> really think about that, maybe that could work. > >=20 > > I think hardcode is better here. xFalse, > 'navigation_depth': -1, > } >=20 > The sidebar configuration is conditional, so we have to pass something=20 > to indicate dts build. I'll change it so that we look for 'dts' in src=20 > in call-sphinx-build.py (we're in the dts doc directory, indicating dts=20 > build) and set the DTS_BUILD env var which we can use in conf.py. I=20 > didn't find a better way to do this as conf.py doesn't have any=20 > information about the build itself (and no path that conf.py has access=20 > to points to anything dts). Here's how it'll look: >=20 > if environ.get('DTS_BUILD'): > path.append(path_join(dirname(dirname(dirname(__file__))), 'dts')) > # DTS Sidebar config. > html_theme_options =3D { > 'collapse_navigation': False, > 'navigation_depth': -1, # unlimited depth > } OK > >>>> +To build DTS API docs, install the dependencies with Poetry, then e= nter its shell: > >>> > >>> I don't plan to use Poetry on my machine. > >>> Can we simply describe the dependencies even if the versions are not = specified? > >> > >> The reason we don't list the dependencies anywhere is that doing it wi= th > >> Poetry is much easier (and a bit safer, as Poetry is going to install > >> tested versions). > >> > >> But I can add references to the two relevant sections of > >> dts/pyproject.toml which contain the dependencies with a note that they > >> can be installed with pip (and I guess that would be another > >> dependency), but at that point it's that not much different than using > >> Poetry. > >=20 > > I want to use my system package manager. > > I am from this old school thinking we should have a single package mana= ger in a system. > >=20 >=20 > I understand and would also prefer that, but it just doesn't work for=20 > Python. Not all packages are available from the package managers, and=20 > Python projects should not use system packages as there are frequently=20 > version mismatches between the system packages and what the project=20 > needs (the APIs could be different as well as behavior; a problem we've=20 > seen with Scapy). Poetry is one of the tools that tries to solve this=20 > well-known Python limitation. I fully agree for DTS runtime. I'm expecting the dependencies are more tolerant for DTS doc. > I've done a quick search of what's available in Ubuntu and two packages=20 > aren't available, types-PyYAML (which maybe we could do without, I'll=20 > have to test) and aenum (which is currently needed for the capabilities=20 > patch; if absolutely necessary, maybe I could find a solution without=20 > aenum). But even with this we can't be sure that the system package=20 > versions will work. We need them all to generate the documentation? > >>>> +.. code-block:: console > >>>> + > >>>> + poetry install --no-root --with docs > >>>> + poetry shell > >>>> + > >>>> +The documentation is built using the standard DPDK build system. > >>>> +After executing the meson command and entering Poetry's shell, buil= d the documentation with: > >>>> + > >>>> +.. code-block:: console > >>>> + > >>>> + ninja -C build dts-doc > >>> > >>> Don't we rely on the Meson option "enable_docs"? > >> > >> I had a discussion about this with Bruce, but I can't find it anywhere, > >> so here's what I remember: > >> 1. We didn't want to tie the dts api doc build to dpdk doc build becau= se > >> of the dependencies. > >=20 > > Sure > > But we could just skip if dependencies are not met? >=20 > Maybe we could add a script that would check the dependencies. I'll see=20 > what I can do. OK thanks