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 8D7F942ABE; Tue, 9 May 2023 17:28:44 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1EE4F42D31; Tue, 9 May 2023 17:28:44 +0200 (CEST) Received: from mail-ed1-f50.google.com (mail-ed1-f50.google.com [209.85.208.50]) by mails.dpdk.org (Postfix) with ESMTP id AAFAE41151 for ; Tue, 9 May 2023 17:28:42 +0200 (CEST) Received: by mail-ed1-f50.google.com with SMTP id 4fb4d7f45d1cf-50bc075d6b2so11416637a12.0 for ; Tue, 09 May 2023 08:28:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pantheon-tech.20221208.gappssmtp.com; s=20221208; t=1683646122; x=1686238122; 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=tbnIKNrCgd73QczGnQsRysRltduCJ3LoE5DKsMPfV9g=; b=LzitLgLbd613UANy7KIAH0dwoHEnZy1n60zcqOsCNGrz9rCtbaYYOnHV3jFr8iEmmn tiHryqkGrxAl8hDR7m2eZmXwKJ5C5hO5oa5k7l01Kq8UiXAeFXKWOzo1TD+CSwOhDOVw l+7WpDPCpGwqZBxNyd8klZ8IDU81BeIYJx8l1yX052JDMvgKXxByINOrVIrmklPcmZh+ nmrDjG3cwNiJLpUQZB04Y4NWib5OQNgnjn0WcOLlGk+X4df35O5cxNY3WtvlSF3Eb8aV FocJJzxsGEx6qCEhD3RF2netANuursn68ynJrAntGGoTXPlmXD6mhrBEHN+rJB8uVU7/ NS5w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1683646122; x=1686238122; 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=tbnIKNrCgd73QczGnQsRysRltduCJ3LoE5DKsMPfV9g=; b=b1UFhggfcYp6fm59ivUoGEDN5maO+mPeMIepo6pBxrLCbmTln1KDeQwcb+q4rPXRdw uhUjV+pSKtk25s6z7z6u4eLO6wBt875nra63S+xM606ViPv3hg1uPThSOrtQD14em/EZ X7NBpAhIJegvpR/A4rbBUN1TcDhc8Z+tAXjDhOo27sLK6UzfUhLQRXjgMHJwLqnZNfFo cDVH78HOHzpcy1zMUV0ZN7IZX+dHcTPYL7xdRNODzcybRiumVS+q+KEiDQLchV1wARvG j8thiVnUlQieaAUpvL3fU4CjSmrEY/y1g1xiHjugIF4rdCr9K4ydtvqoSpkDFcHVOe68 vN+g== X-Gm-Message-State: AC+VfDwhaThjbIblbDEVNu4FEgYERQED3NtnhxV87gBypWMFlr+q/O1y u2wBt+qR2ZMnej4nuRkEjW833tWzS3YuxT6W8OZxnQ== X-Google-Smtp-Source: ACHHUZ6BGg/j5Ib15JGIQgKOv2zUciwX6CMBq2G+f9QZE/eDGo+MRWm/Wvc/7yCzmm50qoVu1rEWsY813GofBxC48pQ= X-Received: by 2002:a05:6402:1b1a:b0:504:e9cc:de35 with SMTP id by26-20020a0564021b1a00b00504e9ccde35mr12029365edb.0.1683646120581; Tue, 09 May 2023 08:28:40 -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: Tue, 9 May 2023 17:28:29 +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.] > > 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? > I don't think any tool for python API docs would be able to do it without the dependencies. The standard way to document python code is in Python docstrings which are accessible during runtime (which is why the dependencies are needed). Doxygen says that as well: For Python there is a standard way of documenting the code using so called documentation strings ("""). Such strings are stored in __doc__ and can be retrieved at runtime. Doxygen will extract such comments and assume they have to be represented in a preformatted way. There may be a tool that doesn't use the __doc__ attribute accessible during runtime (I don't think anyone would implement something like that though), but that would likely be much worse than Sphinx. Juraj > /Bruce