From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 38E1342A6F;
	Fri,  5 May 2023 16:07:36 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id B42FD410EA;
	Fri,  5 May 2023 16:07:35 +0200 (CEST)
Received: from mga17.intel.com (mga17.intel.com [192.55.52.151])
 by mails.dpdk.org (Postfix) with ESMTP id BFB6740695
 for <dev@dpdk.org>; Fri,  5 May 2023 16:07:34 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple;
 d=intel.com; i=@intel.com; q=dns/txt; s=Intel;
 t=1683295654; x=1714831654;
 h=date:from:to:cc:subject:message-id:references:
 content-transfer-encoding:in-reply-to:mime-version;
 bh=HCDODTiWyQ4p3itGGwtvqgpzyvQIHua+pwT3QHGaeR0=;
 b=ca6ztnKo8tORjyUUxBel2CCtAI08Xy+RTofPQ1LA22VIe5uEaVHk/H5U
 g48vPYyKVfPXCZuOU3smiW4bdSrhV4DdF9/hC2DF2etGpm+2jxdcZFb46
 kZT0ehUlF3Z5PQM/9W13dfQMiU8ftXi+n1H4a+iVE4k7AHYrZusaDLDab
 NzRp3igohfYSy4D/3BGiCBGGWDMnoVjlIXNKCQ5TYhh/08Okpn3yKFeBb
 WLiL9y1KFbWrIM7J933tBuHff2D5zRq0Zu8oCeiatCYA1/xtxnZfQflsS
 8c1aXdwJ7j1IXEP522udwEI4nzj7ckoNnLpGBxkfAM5+2h/5KLR3gYm6m w==;
X-IronPort-AV: E=McAfee;i="6600,9927,10701"; a="329570584"
X-IronPort-AV: E=Sophos;i="5.99,252,1677571200"; d="scan'208";a="329570584"
Received: from orsmga001.jf.intel.com ([10.7.209.18])
 by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 05 May 2023 07:07:04 -0700
X-ExtLoop1: 1
X-IronPort-AV: E=McAfee;i="6600,9927,10701"; a="730359614"
X-IronPort-AV: E=Sophos;i="5.99,252,1677571200"; d="scan'208";a="730359614"
Received: from orsmsx602.amr.corp.intel.com ([10.22.229.15])
 by orsmga001.jf.intel.com with ESMTP; 05 May 2023 07:07:04 -0700
Received: from orsmsx612.amr.corp.intel.com (10.22.229.25) by
 ORSMSX602.amr.corp.intel.com (10.22.229.15) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2507.23; Fri, 5 May 2023 07:07:04 -0700
Received: from ORSEDG601.ED.cps.intel.com (10.7.248.6) by
 orsmsx612.amr.corp.intel.com (10.22.229.25) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id
 15.1.2507.23 via Frontend Transport; Fri, 5 May 2023 07:07:04 -0700
Received: from NAM10-BN7-obe.outbound.protection.outlook.com (104.47.70.109)
 by edgegateway.intel.com (134.134.137.102) with Microsoft SMTP Server
 (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
 15.1.2507.23; Fri, 5 May 2023 07:07:03 -0700
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;
 b=XcPq+9oR263P9nisOR3K4ItQ51c7uxmuviYCn+2oa6bK65kTJLAprd+YdWii61Qb3NNlo1BX8quT5m69+BoJLdLTWSMQcen2Me94L6AscGA8Xod6Ejy2ewvqknYTQIUYqsbLAZQeASF1LJ6SYnZWwJWQ8A85VkhF77wVKlHFgaqaCO+LUf9iR9M6UmQjzn0c8JCkoeArJdhPJgKNV2IiiUY2cqm/AOkBF80P4DhPHeXR23ypeIP8s07eLQ2xVIJeAWZo3lrRSKnlJjGgzu2NasypoymZVLmmh+bf2BdjuEdSMUXjGGMOGFtGyHHm5SqtpYkaMr3G04ntoIRYzbiCuw==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; 
 s=arcselector9901;
 h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;
 bh=pbR9I83WM6wSRW8ywamVcBdv1oSI+cESMv7NRo95f/I=;
 b=WHjdsIqxF8dSsIv5iGnPYXI+d/UJc2LNtbAkmVZVYTVKKOCWDgKzwsyf3V1tbJOsNXEshW+lNmIgKUn0q0rLeMiPf5FU871qOpttr6CMW4VvU2c3jJoMIblcQfXx+e1u4sOnkR9ckXKZS1EW3kxAKikOGMf1TLe7k+PTOrLF01V2kBds4pK5AzyBTVWjeOfX/7+kRsBiGs1CLyPRBdHeS1T0ldHFqe/7+smhDBfLgWVjxkSLOYFThro9cULlyuccYyOK/AeJ5v4Zy6KVxEUxdmatB0l092TAPnKFcDUG7zL/A08VwRvjgU5LW6o5659MbNcLlnV7Ab5YSODLSpVlbA==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass
 smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com;
 dkim=pass header.d=intel.com; arc=none
Authentication-Results: dkim=none (message not signed)
 header.d=none;dmarc=none action=none header.from=intel.com;
Received: from DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17)
 by PH7PR11MB6676.namprd11.prod.outlook.com (2603:10b6:510:1ae::7) with
 Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6363.27; Fri, 5 May
 2023 14:07:01 +0000
Received: from DS0PR11MB7309.namprd11.prod.outlook.com
 ([fe80::b8f3:958:d2c5:2232]) by DS0PR11MB7309.namprd11.prod.outlook.com
 ([fe80::b8f3:958:d2c5:2232%7]) with mapi id 15.20.6363.026; Fri, 5 May 2023
 14:07:01 +0000
Date: Fri, 5 May 2023 15:06:54 +0100
From: Bruce Richardson <bruce.richardson@intel.com>
To: Juraj =?utf-8?Q?Linke=C5=A1?= <juraj.linkes@pantheon.tech>
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>
Subject: Re: [RFC PATCH v2 0/4] dts: add dts api docs
Message-ID: <ZFUNfiXmoaKTdmk2@bricha3-MOBL.ger.corp.intel.com>
References: <20230323104040.484708-1-juraj.linkes@pantheon.tech>
 <20230504123749.1417259-1-juraj.linkes@pantheon.tech>
Content-Type: text/plain; charset="utf-8"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20230504123749.1417259-1-juraj.linkes@pantheon.tech>
X-ClientProxiedBy: LO2P265CA0503.GBRP265.PROD.OUTLOOK.COM
 (2603:10a6:600:13b::10) To DS0PR11MB7309.namprd11.prod.outlook.com
 (2603:10b6:8:13e::17)
MIME-Version: 1.0
X-MS-PublicTrafficType: Email
X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|PH7PR11MB6676:EE_
X-MS-Office365-Filtering-Correlation-Id: 83233458-a769-4c76-08ac-08db4d71feec
X-MS-Exchange-SenderADCheck: 1
X-MS-Exchange-AntiSpam-Relay: 0
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: XjrR3dGNVlMl/YoEjUjU5TNJcM8SrnyqCyTOCaf74Rf9pXfnjWHlmwp5ykhbT2XgNhlL61dylY5NSU1ZNp39P4pYronmm1zqWfnNuGRu2wsav0KkeGjmlEi12m0mVMNPvtAU+V0tBJ30Ndd7NvgCA9XJ2HKllnC7PkKR9N4AGKrMQyelAqr62Ow5XECs+FPZswldCD5DP+iQ5FwHDccgjk/w+YqaMmiC6wFcqceIBWKaE2u6L1Y2OS3LVRBK7FNqdk6reCveOC8tC8anm3OCHQKSTyQmFdYQTvF7JdewW1nfIXryIA9ubJKmYELdiHWfiEyBN4rIBUxTT/6D3Rn8gtT1uVob9k/2EdGaWmD/HNIb8zNXZd3MsJUAG3ralO0wFKr+065cp4DjXwU9fxmb6OMvNB4V1CxtlI2TLZ9l+Svb0SEMpipXY8ElKsPEY51h4LrDZpesHknLGdxMpOXRxjCNjhxfBF6y+afGCUzNn/Vc1SfAMfdTekLOr14hV7+kmH5ZvoLgdeo7qpj3fe0O+FYQgnUHuOQX0hTbKCeAOoc=
X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:;
 IPV:NLI; SFV:NSPM; H:DS0PR11MB7309.namprd11.prod.outlook.com; PTR:; CAT:NONE;
 SFS:(13230028)(136003)(396003)(346002)(376002)(39860400002)(366004)(451199021)(83380400001)(186003)(2906002)(38100700002)(86362001)(82960400001)(41300700001)(8936002)(8676002)(5660300002)(966005)(44832011)(6916009)(4326008)(66476007)(66946007)(66556008)(6666004)(6486002)(316002)(478600001)(26005)(6506007)(6512007);
 DIR:OUT; SFP:1102; 
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?azU4Y0lEbll4VjhhcEVQbDJ0YzE5U0lCUUNoM0VReFNxREVKQU5oZXcyYjFj?=
 =?utf-8?B?cVgwQTU0VmE1NnZkMnpKVkM4Y1RwcGFNNmViZytQNXhSRm9qWWFSSHF2M3gz?=
 =?utf-8?B?bHFPaGZTTG9yaW9zMnpiaTV3aitmVHVmN01sVkFaWEVYMkRnajlJSnI3NmlB?=
 =?utf-8?B?dWtRQ3kxSWJyWWQ2TkVpQVdua01kcU9ibktMM2l0MEROOEUxUUdOaDRBdmVZ?=
 =?utf-8?B?MU5SUEJ2U0hCVURKOUZrTzk3a0RWVW11eHR5ek1wSGtIU3RBWk1Bd01XTXlM?=
 =?utf-8?B?RnpMcnliWFM3SzFXbC9lajBZKzZ3T0pNekFvS0pKMUpFZEx5b1pDZm8xRWVp?=
 =?utf-8?B?bnRlTFowdlZ1SktPZHR0Q1NQcEJaOGM3eGxOcHN0ODJ1bzBQQjNaUEJGekpC?=
 =?utf-8?B?RDc1WFJUOWNrMjdlTWoxTzczaUhMSjFuY2Jxd3AzdktLakZmdGpRakNDY01a?=
 =?utf-8?B?UlRHQXg1SGVzYnE3eTc2YnNZZWFUdS9reFV2cjdnR2RQaFE5U0FBcWpTbVow?=
 =?utf-8?B?ZU5IdVZTY3NvV0phQXUrQ0VIU0psQVdqZDU1NUVlbnRBUlQxMXNrakhUYXJK?=
 =?utf-8?B?eFRKVHhwOHc4S3d1NHJBNEVjR0Q4YlBjZGpaYnlBMEhBbThRblhiMk4vNmMw?=
 =?utf-8?B?dENrb2dyMmt0dWsydjRrSHUvRlhhVUhNZGNEWW5PRi8rR1ZVcVR4V3kwT3Z1?=
 =?utf-8?B?bE8xS0JTc1lqU2hwdTRqMmxqSXd6TGdqYTFCSmx3VVhyZGhVYWJMWmxkbE44?=
 =?utf-8?B?U0NSLy9RVTNDUVYxQmNhYlBySHdZNEJFT2MrMXdSelJlemhBNkY4aUVTRWVC?=
 =?utf-8?B?YVpLL01NQWVrTVdTeEhObFFESHFEMWNnSFZZUTdsY1VQUzl5bUpCOU8yV1M5?=
 =?utf-8?B?WHFESGZyeDRaZ0prMW1oekRyTlhzeEtoRWlvZGZqK2FyTDN1MGRZRXBoblRl?=
 =?utf-8?B?NkRxUjRmQUNMQ04vZXNET0NETlFZanFNZlRFZzJucDFmNEdvL3lpM0w1bHow?=
 =?utf-8?B?bXJtYjlDNDE4RXRqaGtFQjdYK2RQcFUwTUFKeUZHQURmVE9sYXo0MGNEY3Q1?=
 =?utf-8?B?eXB0MWhEVVYyNGNQK2paQjRUcmFla2tHU3pBMk9Qay9sbzlNNGtRaDNsckRI?=
 =?utf-8?B?U3hoTUJqYzBJRXhRVFFoS0xGY0h0S29heGlCc1pBdHVDL1Rkd0puWVpaM3FR?=
 =?utf-8?B?cHhNeWc1b2JvT0laeis4am5BdmtjVzAzbTFsN0lJTGdiYzlNRHRNNUF5SUpO?=
 =?utf-8?B?RzVjVXM0Snlad2MyY2xsSUxhbk9mZ3FSU0dtMFFySUY1OFh1OFNHalNVMWtI?=
 =?utf-8?B?dy9KTXVnRTk3REczVUc1U3BQSlBLMTdhNjRaS2R1TUVlbDE2c0pka0dRaDY1?=
 =?utf-8?B?TDNHdExDRzhMMUpYd0hZVUowWmNTQ2dNVmZQTmdpb04vRHpvMVBFd1dKcUFs?=
 =?utf-8?B?NktPK1VtYVQ5Q0x1a1FDcjdDQ3NURHVjcmc2eU8rSWpkeWlWREVYeHhRMDh3?=
 =?utf-8?B?U05RMERwb2VxS1FmS3RqSUlINUR1Y1ZJbWwyU2FzNXlsbEk2Mk1WbFpLNGpx?=
 =?utf-8?B?bDJ1ZFo2UkhYUHVGSTZDV1dRZUxqYlZIZDMxMkdjRTJEei9YYjQ0djViZDhL?=
 =?utf-8?B?ajBxK0V1WlZPaEJJeUtraC9PNzRJOHdoRmdjVzZPdkY0MTRvVS9VTTJzcjlH?=
 =?utf-8?B?TkRiQ3NlS2lFNFdZd2hBQy9OMmxod2RreUxDL011REhnakhGYWcxRS8zbXQ4?=
 =?utf-8?B?V2N2VkdrYUNrcFBrZlNtT3N3NkVYeGl3RjAwQzlQdGxIcHRQYU9SdTlMV2xM?=
 =?utf-8?B?VnlrRTVtY2JZZ2lJZG5tNjdZSVIzeloxQ2tkVEwyQ1ExbGZqTG1BMTcvcnYx?=
 =?utf-8?B?SFQ2VXRaK0J2eENYeWtHZkFPZ3dNZm9oTWE0M1V3RXMxMWFncm1DYkdPZHVo?=
 =?utf-8?B?OGRXK3JxS3NETWw4U0FGMmNLWmdPemNERUdRSU56OCtyVjlnSzFPWCtyeUpS?=
 =?utf-8?B?eW1GZE9zVGdKWUZmNmhYenZOTkdqVUYveWM4OGc1ZFRFUlVyTlZUbmVmZmsv?=
 =?utf-8?B?dTU5b1pJRjRCYVpJbGdhcjlVV2JDQVNEcGFjZytzOHdlblNCUGRCSGloaHRQ?=
 =?utf-8?B?WXlOcEorVXdaYVdVeXZWcWNPMGhIeTNFU2N2WC9SNzVoamFaaksyTzJRTk9Y?=
 =?utf-8?B?K3c9PQ==?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 83233458-a769-4c76-08ac-08db4d71feec
X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 May 2023 14:07:00.9592 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: oTv3+9CV2JeKLGfs6mAIQqVOOu7qcpqaDW53kTJYZOSdT8hsfNTeXbBDkyxlGel4vHORcAOSf4CPaQVgOWU4zttoo4EyJ+iUolru5VL1BoM=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH7PR11MB6676
X-OriginatorOrg: intel.com
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org

On Thu, May 04, 2023 at 02:37:45PM +0200, Juraj Linkeš wrote:
> Augment the meson build system with dts api generation. The api docs are
> 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 <meson_build_dir> 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š (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 run
specific commands in specific directories quite awkward. With this patchset
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 tried
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 DPDK
uses doxygen for this, and since doxygen supports python can the same
tooling be used for the DTS docs?

/Bruce