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 9EBB342A1B; Thu, 11 May 2023 10:56:06 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 78C5C42D62; Thu, 11 May 2023 10:56:06 +0200 (CEST) Received: from mail-ej1-f49.google.com (mail-ej1-f49.google.com [209.85.218.49]) by mails.dpdk.org (Postfix) with ESMTP id 9082242D5E for ; Thu, 11 May 2023 10:56:04 +0200 (CEST) Received: by mail-ej1-f49.google.com with SMTP id a640c23a62f3a-9659f452148so1475395166b.1 for ; Thu, 11 May 2023 01:56:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683795364; x=1686387364; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=+fg0zk4pKsoL4y/euNPAut6ZOFbq3t7u0Tk3hUoGKZE=; b=cLNLVHcogUDZsQt8F5FKR0ibGesSLyqJN0OulKr6bqW+kcDqgwU7rXs/FntYJEzkZT 1JKPN1lbyYKg46o+rYOVYDQIDbg7VOLE8Z1LRtx2drbnwpdC36IiiMpohX2hqQ37W63+ ZxiLxNVZ7dskGKoTUKDAW8eB9Mm0r0c9xhy+PLNTB45wV0Krs3L4oVuuOYnl+T3Zq2Fe P5x8KX7GJxE/4JXIW55fx9iDkYo0px3c4wmsc4MpyaoJuYkZRnbZnKJaFYzZjO8Cx0F6 S8/hgGtpDNf6mnQcAiAbuMnqT7b6S4sY17V3B1k4sc2BUc8E06wfKBT4AT0kMP46nIPU vPJQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683795364; x=1686387364; h=content-transfer-encoding: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=+fg0zk4pKsoL4y/euNPAut6ZOFbq3t7u0Tk3hUoGKZE=; b=YBsPUTIDf6MjvvSE2IQyT1gqrpg7MQsgil7x7JsKXYNgWyIJRc51OVuPJ5uByD4KFq x9pnABgD8lBWxJCzhELg//Yup0roFbpw3nKUPJ/2sPw1qnzVclg7utB28CRO8N9GtuE5 k/CGd8psx0wJPc/euIMkjtBk1mYX88toU86u9vUfY/rqbzYeXWO7BrWVMUXgTtz8Oamn HUM7wz6g929AQYmGG1K50fqprQ5YqglQbj3jCQlspUyUS4bgJAwTZxXrDDReUxd4lhkA zsWkwQqpIxMAYKIB6FPp7GyuGryj9BpPtaph6D40w0tI87/iyc0HmcEytvtyKwDy/HO+ px6g== X-Gm-Message-State: AC+VfDxWrRZef3D+L3lg1yrY5CrIiX7vpXohr3OsaxveRLTCBtDxPZB+ 13yW0pH9Cn68g7Q5PgQlrwW7ThTd1COcOwjYfRtrZw== X-Google-Smtp-Source: ACHHUZ7fwT/lj1zEssGFxPAp8UujU4MchdlMrFw292FVmB7OrhzlGDTjpWGy8lw7AE6ELA18paSeR7W3jannZH41cOw= X-Received: by 2002:a17:906:974b:b0:957:943e:7416 with SMTP id o11-20020a170906974b00b00957943e7416mr20619641ejy.15.1683795364361; Thu, 11 May 2023 01:56:04 -0700 (PDT) MIME-Version: 1.0 References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-1-juraj.linkes@pantheon.tech> In-Reply-To: From: =?UTF-8?Q?Juraj_Linke=C5=A1?= Date: Thu, 11 May 2023 10:55:53 +0200 Message-ID: Subject: Re: [RFC PATCH v2 0/4] dts: add dts api docs To: Bruce Richardson Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, lijuan.tu@intel.com, wathsala.vithanage@arm.com, jspewock@iol.unh.edu, probb@iol.unh.edu, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 Fri, May 5, 2023 at 4:07=E2=80=AFPM Bruce Richardson wrote: > > On Thu, May 04, 2023 at 02:37:45PM +0200, Juraj Linke=C5=A1 wrote: > > Augment the meson build system with dts api generation. The api docs ar= e > > generated from Python docstrings in DTS using Sphinx. The format of > > choice is the Google format [0]. > > > > The guide html sphinx configuration is used to preserve the same style. > > > > The build requires the same Python version and dependencies as DTS, > > because Sphinx imports the Python modules. Dependencies are installed > > using Poetry from the dts directory: > > > > poetry install --with docs > > > > After installing, enter the Poetry shell: > > > > poetry shell > > > > And then run the build: > > ninja -C dts/doc > > > > There's only one properly documented module that serves as a > > demonstration of the style - framework.testbed_model.node. > > > > [0] https://google.github.io/styleguide/pyguide.html#s3.8.4-comments-in= -classes > > > > Juraj Linke=C5=A1 (4): > > dts: code adjustments for sphinx > > dts: add doc generation dependencies > > dts: add doc generation > > dts: format docstrigs to google format > > > > I find the requirement to use poetry to build the docs, and the need to r= un > specific commands in specific directories quite awkward. With this patchs= et > there is no ability to just turn on the build option for the DTS doc and > have the docs built on the next rebuild. [Also, with every build I've tri= ed > I can't get it to build without warnings about missing "warlock" module.] > I want to ask about the warnings. This suggests a problem with dependencies, have you entered the Poetry shell? We may need to add some steps to docs, which are currently: poetry install --with docs poetry shell And then: ninja -C build dts/doc Maybe the problem is with Poetry version (1.4.2 and higher should work), which is not specified in the docs yet. I need to update http://patches.dpdk.org/project/dpdk/patch/20230331091355.1224059-1-juraj.l= inkes@pantheon.tech/ with it. Which are your exact steps for building the docs? Juraj > From what I understand from the patchset, the doc building here using > sphinx is primarily concerned with building the API docs. The rest of DPD= K > uses doxygen for this, and since doxygen supports python can the same > tooling be used for the DTS docs? > > /Bruce