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 603E9454E1; Mon, 24 Jun 2024 15:53:45 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4691F402F0; Mon, 24 Jun 2024 15:53:45 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.14]) by mails.dpdk.org (Postfix) with ESMTP id DB67E4029C for ; Mon, 24 Jun 2024 15:53:42 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1719237223; x=1750773223; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=h+AlSZ2M8OyAcYw5ro9IigxcPsioTKvqPq+NqmLqheg=; b=cMwi6qtydaZrW5I133S2Ed2HYLRBz3OOxjmvLfN5QoQk8KcJXc1GVf++ M8aM6JGg9JYJWEQmXthD0um0pLWD2Hl53RAv4Ovd/ysUOlgz7lv4xba8g wnysk/gXzyPm+TW3R7SsSPe+6q3xpAxNhjA406Z4ogCiPZ1s0uOC9RMzf zSlrUsUo/0gzrBPBvA/fJe2ox+iFussM8qFM2vS5QsIKjaEDvwlquNAGT 8ZfD4HAc8z37vtSzjUVm9psKq5EUHUBip4PbzXQ12jkDrkizMcA6OrmeE dmNOxGjfwjimB1BG4gMxnv1XwusIznOgX77gZyVTfI0GBGi2sFTU5xGjS Q==; X-CSE-ConnectionGUID: ebSQpTiHR3Si5wfFGUyJIw== X-CSE-MsgGUID: yCcyU3BYRsmC9b+ezSF8ZA== X-IronPort-AV: E=McAfee;i="6700,10204,11112"; a="16438728" X-IronPort-AV: E=Sophos;i="6.08,262,1712646000"; d="scan'208";a="16438728" Received: from orviesa006.jf.intel.com ([10.64.159.146]) by fmvoesa108.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 24 Jun 2024 06:53:42 -0700 X-CSE-ConnectionGUID: CX439ooWQHSd5CDZDNhvjg== X-CSE-MsgGUID: c/Kh8KWWRjyfpl97s2o13A== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.08,262,1712646000"; d="scan'208";a="43740331" Received: from orsmsx603.amr.corp.intel.com ([10.22.229.16]) by orviesa006.jf.intel.com with ESMTP/TLS/AES256-GCM-SHA384; 24 Jun 2024 06:53:42 -0700 Received: from orsmsx610.amr.corp.intel.com (10.22.229.23) by ORSMSX603.amr.corp.intel.com (10.22.229.16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.39; Mon, 24 Jun 2024 06:53:41 -0700 Received: from ORSEDG601.ED.cps.intel.com (10.7.248.6) by orsmsx610.amr.corp.intel.com (10.22.229.23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.39 via Frontend Transport; Mon, 24 Jun 2024 06:53:41 -0700 Received: from NAM11-BN8-obe.outbound.protection.outlook.com (104.47.58.175) 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.39; Mon, 24 Jun 2024 06:53:41 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=V/FM8Hmv3ZEFSGJ3BpPJ8HczTlbE18l0O36aajs/AEnH+SudL0mn9V9cAzIPpdR1cgWYhju0jQduGLv2RGoXA+kRmboTIIn6xP53+vE8K4XjWGhKeDAhTji18z9aleWs+5lnVwiJJl4sQ+1POwBeXblMkv2UCDiaw9hgYW2htsirQmu+9UE6KcveNQ/+6Xjx2G2gzYUpF6Aq/Iw7mXD2byWjJAOMRYol8FQI02uHekWFRlzlwm/O0HORwGfgsxX88ntNeGil6s7mSxWimMhjF51WSSvjbNjPpVAM/bSBeZgGi+orBFrEh3x3O2bWN9+tbN1EqpXlbk5YVf9J7sLprg== 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=4mW0JzsgFJa3WcMpDzDiD/T9RnEzCw8LuoBGbzEW7n8=; b=LtB9e0fDXBB6+l/fa4yGrxTHOwy9ZDsx1JPuzsjgIakg6VWPmhOxF2wTHHTo5amojJ/dzUg9IwJs39Srd3fDeD01AlcaPbt0E8eH1kq1sWDVTqOaSQDUm8IccLEOOaM4wWzGlhK4jHakfOjNFq9oxeePBtNBl/L+7RVYnAuKokOl/WxXTVs/ZM4BgH6vroAaQdKcH032EFfSUqkGBTwtiphGGdHZ2Ppz3fjPrbJaRx/rbgVWCJvWnt/2pVurmSLvYj1WT4lx5kGGqr53krbNaQWImcuNKNnR/r9XPlQpyRTO2YH8jbQ4n1O4ZE21kbcwlOtSyqNdLEmf1ZBJbZ0KnQ== 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 SN7PR11MB8284.namprd11.prod.outlook.com (2603:10b6:806:268::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7698.25; Mon, 24 Jun 2024 13:53:38 +0000 Received: from DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::f120:cc1f:d78d:ae9b]) by DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::f120:cc1f:d78d:ae9b%7]) with mapi id 15.20.7698.023; Mon, 24 Jun 2024 13:53:38 +0000 Date: Mon, 24 Jun 2024 14:53:32 +0100 From: Bruce Richardson To: Juraj =?utf-8?Q?Linke=C5=A1?= CC: , , , , , , , Subject: Re: [PATCH v6 4/4] dts: add API doc generation Message-ID: References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240624134600.31500-1-juraj.linkes@pantheon.tech> <20240624134600.31500-5-juraj.linkes@pantheon.tech> Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20240624134600.31500-5-juraj.linkes@pantheon.tech> X-ClientProxiedBy: DU2PR04CA0203.eurprd04.prod.outlook.com (2603:10a6:10:28d::28) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|SN7PR11MB8284:EE_ X-MS-Office365-Filtering-Correlation-Id: 7fef26ea-18b3-4b5d-cd9f-08dc94550c53 X-LD-Processed: 46c98d88-e344-4ed4-8496-4ed7712e255d,ExtAddr X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0;ARA:13230037|1800799021|366013|376011; X-Microsoft-Antispam-Message-Info: =?utf-8?B?VmZ1OTJ1QXJMejBlMnFacit3U2l4cEpGb1FMb2x6czl4aW9kR2FQT0tnaXo4?= =?utf-8?B?Z2VzdDBrc0kvMnMxVkI0TWhITW5pQ01xdEVlUHkzUmdoRjdXcHpPZWxvUHhX?= =?utf-8?B?SWJVajFRZ0xPTnpkM3JzalFWR09OK285Y01FWFNuRTZKT25telpCa0VnRkUy?= =?utf-8?B?VmxCNUovR3hYTmw4WU0rQ3hCZWZGYjRyc2JTSWpWYXg3YnV2amlhdVBXZEU4?= =?utf-8?B?dVNZK05RWDJpREpQaWI0VVFpVVhmSGllcGlWQ0NpTHg0V3dNNGRkRkdnb05M?= =?utf-8?B?V3oyNi9zd2xyMjBPVE1kSmp6WnR1TzBxcjFwT3JnWW51WUhwS3ErS2owQUNp?= =?utf-8?B?cUdLTDI5VEhzU2E0U001YWNKbFdaZXAxWU95Zld2RzIvR0tJN0xhMnVON2N3?= =?utf-8?B?MmU5VGkycFZZZXhMa3hiMU81eW0rdGg0emNSSVlpNkVTWnpDNitQMzBoY2RB?= =?utf-8?B?MUNnam80c00yYjREMVBkRkxVVE5rVUVaMzBOZ2ZtazZ1YTdvcVJCVTNFMXFZ?= =?utf-8?B?Q0d1UmRxNDFwOUE0WXdaT2pWdWlNK0lHcmVxQi9JODJXcmlkaWZyZy9zQ2t5?= =?utf-8?B?Ym5aQUw5U2VTanloNTB1UEg0N2t6M0t3dkRxYzVKaXNHYVMzbVU1ZmtEWGJF?= =?utf-8?B?YXlaVzRibWQ1OUczb296VnVBS0xOK1lwQ2toeksvRWw5bldCTitUbGhxSG9E?= =?utf-8?B?L082QjhkRHA1MkdvQjVOdmtNa05EWGZoUEdCdUd0bjM0eitiekVDZmM3UjFJ?= =?utf-8?B?alhLZk9QalFab1M1Mk9LSlFFRml0N0t0RUNrR29ZR3pGT0twbGFUUUNqeGpy?= =?utf-8?B?Nm5oZ3BDWHM1MjJEN2NPd1FjcFlSaVdRQmdTcHo1QklNLys2c0d2N1Uxa0cx?= =?utf-8?B?eHhwSVVOL1I0encrSHBiaGNpME84Y0dWU2wwR0hhWXpvYWhIY2dCd01yYzNk?= =?utf-8?B?SURXYXJPUXozWW5MaXR5Nlk0d043TG8wZ1FVNFZNL0NFZUhRYXl1Nm5UaExr?= =?utf-8?B?d2NiVlhCd3h3S0Y2YVQrYlYwZFlVdFdZZE9tRkRVWFRmZHAwTEZiMlEvb3Ba?= =?utf-8?B?RzlBdUR5U0JXcnhDU1hGenBTM2VmV3VjRFhTWnljV2NUOVhKQ1QwbDhQSXpu?= =?utf-8?B?c3pZV3JqNHVKMks1dElTYnI3KzVyQkFsc0ZJNlZ4NzJmVDBqNExicXllL0Yy?= =?utf-8?B?MytBMitvdithZEIyaU9CNUdmd24yQ2QrbHFFYkR4SEd4a2ZzL056UldpaXk1?= =?utf-8?B?YU1jeGhNeFJCanl2Nk1wdFhtellxNUFsb3FodU9FcGNLeERIaStUcFdaVHFw?= =?utf-8?B?TGc0WEhjN3VSVkhLdUViK1UvSHNiTzJqT2k2ZExkbS9DTzFMREp4S2dXZGMz?= =?utf-8?B?WmhJU1VpbEhvOC91T3E0bXE3aHJYV3habU1XWWh5eWxvOVNNZWQra2gzc21F?= =?utf-8?B?S1laMTNaZVQvMW0rUUYzYVVFbjVqT1dqRVNrOXJpdUxFVkhTWXA3cXl5eEZm?= =?utf-8?B?SEJoT0dvMDhLU1U5NXFsNGRWbFdhMlpSdkxTRHVuOFcxVWhzNE9GaE0zc284?= =?utf-8?B?WTBHZHJSRVFDN0l5RFJIRGlvOW82akUzemVVZXFWZ1hXdnFwSHhTTldMb3R0?= =?utf-8?B?bUYxbHpLTndUK3hqZHNlUE82TVRUSENDc2Ezd014S3NpY245aVkxRVptRHhM?= =?utf-8?Q?8bXTlmLf3J4b2AYU72ec?= 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:(13230037)(1800799021)(366013)(376011); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?bGY0eDdoWHc4dWxPWk9uNGRWN0ZwM01FQXJYZWVpaTJKRDFoSm1PWUxmVi9a?= =?utf-8?B?Z0I0V1BsK3hhYUpXTWhYa201cHhHVVRGcUNkVE1kM1FoeU9TTE1CTXlOR21W?= =?utf-8?B?RGJMendqVjRVanBzdlFRd0hoNjRQNmpVSzY5bmpUTXlsbjJNU1E2dHRUTkV6?= =?utf-8?B?UjdGeUpzajJTcC9kRkVqY3N6dWVaYmZCOWtUcjZXZ2Y5N0t1L0RrTVJIbjlU?= =?utf-8?B?RCtGTHRkTkwrbXpWK2VuY2ozRUVDRkFqT0ovOUtCM1FubzREN1ZqcEhNSDBp?= =?utf-8?B?UXNqVkRZbDU3ZUtWRlFyYnJ3N0l0UmZVZzVXbldJNVM2eTA0ZWx5NWJQN0o3?= =?utf-8?B?d1RkQzZnS0tMcHRIS2FEUm9uRHJCNFE1cUZnK01EVHJjSVBrdUY0NTJ6RjVl?= =?utf-8?B?eUE2T3dpVFRTUnFBVzhiZThCUkIvT0ZVNmQwL2prTmovc3ZPcGtCSkk2c041?= =?utf-8?B?Z0JWV0dzem1JODJDR1B6ckRIMklYMzRwUkdkUWN0M09hS29uVU9mNjE4UWIz?= =?utf-8?B?RDRnTEErSCtVRWQyQnBvMzNzaVJsTmgzRHJZakwvYVFUdlNFc1dySVRwMkRL?= =?utf-8?B?dG1DM2I2THVJU2RnL04xQk5oMU42R2g0c1o2Y29ndGRNRmhLSU9BWWhaZFRs?= =?utf-8?B?ZzdnSHVPNEk4c1RQQmFZaUNWZ1VhQnBnRlI2M2F0WFhrR1gyS0xPMU9XRDNq?= =?utf-8?B?amlXYnA5MlVzbzNERS9VNURWVzlTZkE0aDRKa3JNZVdScVhWellialFJS0Fq?= =?utf-8?B?bEtjYTVrRVNEQ2pYZUc0OGRubkZWMFdnQzYxVlE1SFdQSmhtT3hsV08zU2I3?= =?utf-8?B?OWNUZ1BBYkZFSVREZzlCUzJNQS9NSkoyL1c4RlA4L1FVR2hSMVMvcmExVjhE?= =?utf-8?B?dFpQV0dQRkswUW9JM3VIb2VsYzhsUFMwZ2pQVitXWUZUb2V0T2FPaUpjd3Mz?= =?utf-8?B?UFVVT0VGMG90Z01UUWt2UFBnbGRqWlJNOHlaRE5VbkYzQkIrL3g3ajMzSG9J?= =?utf-8?B?aXc3M1U5aGN5WXIwL2VTTjd5VTNoVC9ESmhDVjlOQVVjZzJpbzYyZjNNQngx?= =?utf-8?B?VzZEa0VTejVoVjFlWVNDUno0TDdESEt0RzVYNVl0aklCL2FRU0N6ejJBZmVO?= =?utf-8?B?bDZ5bk5HdnAzRElSWmhaZStjUHI2bENMLytPcWxFd0tyUjZ4eXd5Vk4yeFVh?= =?utf-8?B?U215ZG15SFVsT0N4ZWhJRXhwak1sTEY0MTdkNXlKZzFXZExUV3U4TGpkTGZB?= =?utf-8?B?WTVWVEZWWUtESGwyYWlUZExBRUFYdjJCVVdxOUpXOFcxditSOVdaTUpoS3JC?= =?utf-8?B?UURwL3Q5WUQxY09kcDZvOGV0U0ZwUnd0Y2wwVzQ3SGVHenZlT2pLbUVrMi9n?= =?utf-8?B?MTF2QXNjK0RVRnhWR2RBbSs4OXVtd1VHcDBxS2YzYjllVHNRdTZiTHVsOTk4?= =?utf-8?B?Ry9TZkYxUjJ1Q1BsWXd4Q0xHY0xvNjl1WkNDNVhGNGFjZUFILzJSQ2pRRUNP?= =?utf-8?B?cmk1R2J3aThBM2RwTnFPT204N0dKaktZaTFFYlpWNThoUUkvNE54ait2cWxv?= =?utf-8?B?cThBYmJLQUFVNllCcmNWTU1UQlNVWVJ3a1MrRDNDQzlaN1EzWFQ2VkhyWmJ3?= =?utf-8?B?K2dCWXlYc2hDYjBMTlAwUjc0Y2wvcTMwSjZHRXE3SW5BVmJiaE5uV1R1N1Uw?= =?utf-8?B?QnZhSnpld3o2WklVWXVsYlV5K25mYkhYV1N2Wm1zcWNRZTF0VGhZcFlxaStr?= =?utf-8?B?MDVieWs1NlY5TGNxcmczUllaT3BVZ04zVWF1YllycWUyelNWU1pOMGNJRWhI?= =?utf-8?B?WGRraUF2eHI5ejdjTjNvUnpFWEtnS1l0V29Cc3Qyakw3bHlLWkJhSUR0dHp1?= =?utf-8?B?bGdGVGlKTXVUdHNmRjlROWZuSmdrYmhxb3k5UmQrUUphbkQvSW1TS1dGSUIz?= =?utf-8?B?Sk1UYnBNRkNGMGZzQTVhS2dDR0VPMnhyakNnVmdQTVNqSHJwL2t0czVuV0pF?= =?utf-8?B?TGtydjlIc3lOVlRTTW1nL2o1QU5RdXE2SVpCTU56UlMrQUI2VjNodXJ0UEMw?= =?utf-8?B?bWt3VUVyVlh0a0ZJWm9XUm13eGQrZStFUkViSTFSalZVanpmMk5vYmhhN20w?= =?utf-8?B?UkJ2dXkvQ2xkeG94c2hDRTJ3cG1qS2pDV3VEWFFPL0lVZmhWMzdsd2tubnV3?= =?utf-8?B?T2c9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: 7fef26ea-18b3-4b5d-cd9f-08dc94550c53 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Jun 2024 13:53:38.2348 (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: YLQQudEhvwtdmmQEPd/N7I5+5nPAxyiVKzUygM9ix0d3jznvp+YOjpSShae7AORkybC8CdNTxKpYPOSZfOzXFvJVfRLRMhUX6UyZ/DzQUuw= X-MS-Exchange-Transport-CrossTenantHeadersStamped: SN7PR11MB8284 X-OriginatorOrg: intel.com 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 Mon, Jun 24, 2024 at 03:46:00PM +0200, Juraj Linkeš wrote: > The tool used to generate DTS API docs is Sphinx, which is already in > use in DPDK. The same configuration is used to preserve style with one > DTS-specific configuration (so that the DPDK docs are unchanged) that > modifies how the sidebar displays the content. > > Sphinx generates the documentation from Python docstrings. The docstring > format is the Google format [0] which requires the sphinx.ext.napoleon > extension. The other extension, sphinx.ext.intersphinx, enables linking > to object in external documentations, such as the Python documentation. > > There are two requirements for building DTS docs: > * The same Python version as DTS or higher, because Sphinx imports the > code. > * Also the same Python packages as DTS, for the same reason. > > [0] https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings > > Signed-off-by: Juraj Linkeš > Reviewed-by: Luca Vizzarro > Reviewed-by: Jeremy Spewock > Tested-by: Luca Vizzarro > Tested-by: Nicholas Pratte > --- Acked-by: Bruce Richardson