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 C4FD045741; Mon, 5 Aug 2024 11:04:26 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 829C0402B7; Mon, 5 Aug 2024 11:04:26 +0200 (CEST) Received: from mail-ej1-f53.google.com (mail-ej1-f53.google.com [209.85.218.53]) by mails.dpdk.org (Postfix) with ESMTP id 60A96402AC for ; Mon, 5 Aug 2024 11:04:24 +0200 (CEST) Received: by mail-ej1-f53.google.com with SMTP id a640c23a62f3a-a7aa4ca9d72so1191641466b.0 for ; Mon, 05 Aug 2024 02:04:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon.tech; s=google; t=1722848664; x=1723453464; darn=dpdk.org; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:user-agent:mime-version:date:message-id :from:to:cc:subject:date:message-id:reply-to; bh=GPyOJWT9AjvP9RFEoVjlYiK5yxjXw2Zg35/bKDUUFyw=; b=XOhUc4kNQEu/cdZzgdijzQLtWqcjSNT6BD0DLTgcBjBtEYKH9ORK9mFeHDZuOE08hc CCtutTY4uFhIedejcQialRK6XgDaGkOX+dg+7iVjNYgi43M3dTkCbA2l3igQXKw6KJL3 9zBnNSaKFgsPK+y/FOVAu1hQYkAIyDnJDpXitLLDvVYGt6x85e9KVk/h3S48zTwTbAu9 RoLefSzkfhnazMmzCSn8m+eQMRUFgaQMBlLinpVu9wBKjUMRKyYtHEDlQ86NAKX7gFcc MmqbnYoR4WEsB+GRwVBFEP+i7yb75lMtQPX1k3oA55R5O2VGvS38Wkz5xm/6FIv/27MH G6iw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1722848664; x=1723453464; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=GPyOJWT9AjvP9RFEoVjlYiK5yxjXw2Zg35/bKDUUFyw=; b=XT+M38rrbAInMBz3OWu03nsYfgu/zKgQAfpvoHvCa0TgGaUVWA34Q2F5rXtWsxnHqj dGTiCQP8QTw8aaaRVoJxMk22PASxHo3kfGYI/MTamV4DHAh/BEn7kzOPEoGL+fRhxrkb hJG/kZCkutzN+CtPAyOCgp8eRRgSoWP4vLpz+wAVs8aZ9JugdoHIcmV8Jmj1zLXGu5Uy PYhqyIe0bo0WxE77V3SSJI/UR4qntCyH84leWBeyB1Lyy1b2OwAgcG85/Un0mhkNMN95 pJxXMCWJdU/DV8drHBDxbKFcLLcY2SZ0dcNRAP2FFyAyifoZTdfBdBJdpMrBN6tNlcZF wKXQ== X-Forwarded-Encrypted: i=1; AJvYcCVMLIKr9wesCNNJPDs8nAuU9K2CS1Ekoj7IUyfXlsarLm01+4lbGeh06iozlQm+81SjOayOT/MtRc4a9Bw= X-Gm-Message-State: AOJu0YxIZXdKx56iwcuwNujy8zJlWlPdvuenLuciTG6+Z2Yl3Qoan5gm Oz0AiUk4s6I1LUT7sFoVoiXKiua3E/GYg6Y0NHzIQk6Auljo5Y2V09cTBh726qQ= X-Google-Smtp-Source: AGHT+IG9pKZ7urV9UoEoLPyBhcA6IOpgpa66rMAGrncs+cb0dkGSJ9+xzq/UAYg2hXV6kjPZVr6NHg== X-Received: by 2002:a17:907:608d:b0:a72:6375:5fc4 with SMTP id a640c23a62f3a-a7dc4da7013mr829038166b.11.1722848663800; Mon, 05 Aug 2024 02:04:23 -0700 (PDT) Received: from [192.168.200.22] ([84.245.121.236]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a7dc9bc3ce6sm426905566b.4.2024.08.05.02.04.22 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 05 Aug 2024 02:04:23 -0700 (PDT) Message-ID: <894080e7-fcf2-48ea-b8f4-c85bc74cadd0@pantheon.tech> Date: Mon, 5 Aug 2024 11:04:21 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v8 5/5] dts: add API doc generation To: Thomas Monjalon 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 References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <2336017.ElGaqSPkdT@thomas> <5322c7b0-4935-439b-b8d5-a11bdac15150@pantheon.tech> <1801384.VLH7GnMWUR@thomas> Content-Language: en-US From: =?UTF-8?Q?Juraj_Linke=C5=A1?= In-Reply-To: <1801384.VLH7GnMWUR@thomas> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit 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 On 2. 8. 2024 15:53, Thomas Monjalon wrote: > 02é x/08/2024 12:48, Juraj Linkeš: >> On 1. 8. 2024 17:07, Thomas Monjalon wrote: >>> 01/08/2024 15:03, Juraj Linkeš: >>>> On 30. 7. 2024 15:51, Thomas Monjalon wrote: >>>>> 12/07/2024 10:57, Juraj Linkeš: >>>>>> +dts_root = 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. >>> >>> I think hardcode is better here. xFalse, >> 'navigation_depth': -1, >> } >> >> The sidebar configuration is conditional, so we have to pass something >> to indicate dts build. I'll change it so that we look for 'dts' in src >> in call-sphinx-build.py (we're in the dts doc directory, indicating dts >> build) and set the DTS_BUILD env var which we can use in conf.py. I >> didn't find a better way to do this as conf.py doesn't have any >> information about the build itself (and no path that conf.py has access >> to points to anything dts). Here's how it'll look: >> >> if environ.get('DTS_BUILD'): >> path.append(path_join(dirname(dirname(dirname(__file__))), 'dts')) >> # DTS Sidebar config. >> html_theme_options = { >> 'collapse_navigation': False, >> 'navigation_depth': -1, # unlimited depth >> } > > OK > > >>>>>> +To build DTS API docs, install the dependencies with Poetry, then enter 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 with >>>> 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. >>> >>> I want to use my system package manager. >>> I am from this old school thinking we should have a single package manager in a system. >>> >> >> I understand and would also prefer that, but it just doesn't work for >> Python. Not all packages are available from the package managers, and >> Python projects should not use system packages as there are frequently >> version mismatches between the system packages and what the project >> needs (the APIs could be different as well as behavior; a problem we've >> seen with Scapy). Poetry is one of the tools that tries to solve this >> 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 >> aren't available, types-PyYAML (which maybe we could do without, I'll >> have to test) and aenum (which is currently needed for the capabilities >> patch; if absolutely necessary, maybe I could find a solution without >> aenum). But even with this we can't be sure that the system package >> versions will work. > > We need them all to generate the documentation? > We actually may not. The Python docstrings are part of the code (stored in the __docstring__ attribute of everything), Sphinx (more precisely the autodoc extension [0]) imports all the code to access the docstrings and to do that, it needs the dependencies. However, I found a config option that mocks imports from the specified modules [1], so what we can do is list the missing modules there (and we can build without the dependencies). If we do this, we could emit a warning from Sphinx, although the resulting docs don't seem any different according to the basic tests I did. So this means we can do a build with both passing the target and passing -Denable_docs, provided I won't encounter anything wild. I'll change the docs accordingly. [0] https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#ensuring-the-code-can-be-imported [1] https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports >>>>>> +.. 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, build 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 because >>>> of the dependencies. >>> >>> Sure >>> But we could just skip if dependencies are not met? >> >> Maybe we could add a script that would check the dependencies. I'll see >> what I can do. > > OK thanks > >