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 AD62342A6E; Fri, 5 May 2023 12:24:43 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A18B541144; Fri, 5 May 2023 12:24:41 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id C4C7F410EA for ; Fri, 5 May 2023 12:24:39 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1683282280; x=1714818280; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=arH9g+vs5rLB5ToCTCb/erxMW4pfcpkoQ6nH8JSlYR0=; b=nmi9UEo43WBoko5nkGkGahjQUAFVkbzwr5w41l++etVhH5DJJ8ElspDy DI18s8F4Uqj+khyh2qc4a7BNe69ZMfHmNaWtP1jr4GNliNtYYNZwO2inz jOtwrgyrH3ttKk3ODZSixlMGGZZu/Uec0SV47PouC76X/b07TIjrWC6U2 iySKdHzysCMoPV3A82JYpDnwGVtF+EpmYqQ+e9LVcfAXxmYU4YJ9B/+uV Rq9FIyP/hCu/l7WMf48k0l/pGma8AXJiMYYgqoCHs2DjkDWDmvyk9R015 iu2OgHrcYchCpIvOL3q507HrlE5veHst7SSoFvdTFVhV2TUROQKpncwuG g==; X-IronPort-AV: E=McAfee;i="6600,9927,10700"; a="414713177" X-IronPort-AV: E=Sophos;i="5.99,251,1677571200"; d="scan'208";a="414713177" Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 May 2023 03:24:37 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10700"; a="697511844" X-IronPort-AV: E=Sophos;i="5.99,251,1677571200"; d="scan'208";a="697511844" Received: from orsmsx602.amr.corp.intel.com ([10.22.229.15]) by orsmga002.jf.intel.com with ESMTP; 05 May 2023 03:24:37 -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 03:24:37 -0700 Received: from orsmsx603.amr.corp.intel.com (10.22.229.16) 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; Fri, 5 May 2023 03:24:37 -0700 Received: from ORSEDG601.ED.cps.intel.com (10.7.248.6) 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.23 via Frontend Transport; Fri, 5 May 2023 03:24:37 -0700 Received: from NAM10-DM6-obe.outbound.protection.outlook.com (104.47.58.103) 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 03:24:35 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=CL09wPWK6sDf16ODXkuK4WY6yT9M2mqrk8qpiGG8hqtpa6cgf0cpldZhKceRe/OKtWMpWNUejSeL6euDm3EgCu/Nau+MVaPYSGUE37PkXgsYf7w7gL6rFwCT2OiWZopJK4P6NitaWFM5FJnfzbMfyTzUXybfhzcVfCQsHS0x87lQFddhi/PlnpwH/+9wbDZIbs2RWkA/e7499ePgxwrtAdDe0EgdS+1ZTGjRRGNAflpKlyDtl0bmQuKPMVGUlTBHLBcGL0K1D/KECawyPHzBVNxRcN3QIz6VOdlPxY27UbhmBB7TialSHOXJ57v1wlKmICqCbxVCwfNuMcdpJkemAw== 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=nCDoQbildSLMBF47vdSM2xKY2+rpmq8VZoX5I0l/a+w=; b=TYGhWDUDisUF5ByrSPYD1/0DfAD48Jm0LrM/hOO2azkCcxStPKtu4vSuHULMf+4g59Q8FHmU1jBnE3gUw4zzXdTG9RTkMoDnYH1OlQbs8azpKOv01uLd1dpN61euwQTgFj3slZrUNqIBqLeTPG+/1bGUDoFKqY9fFAs+ezk2iXI6ZlxvP/dhNNlYsnhbG91AbMJg7r0ZNuY+bZx3NBbQjDZ6XcKqRFv56mazphiVRKFQRnzwUBBOLF9rqK9sUC2epD/WH36gsTqAKtDJ3f3IIq5sy42qhnKE6PoLMJ3DqeD5TWAO1UjlBs7cgi9j6STNuDcSx92fWnFuxKUVzvAZbw== 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 MN2PR11MB4663.namprd11.prod.outlook.com (2603:10b6:208:26f::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6363.22; Fri, 5 May 2023 10:24:34 +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 10:24:33 +0000 Date: Fri, 5 May 2023 11:24:25 +0100 From: Bruce Richardson To: Juraj =?utf-8?Q?Linke=C5=A1?= CC: , , , , , , Subject: Re: [RFC PATCH v2 3/4] dts: add doc generation Message-ID: References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-1-juraj.linkes@pantheon.tech> <20230504123749.1417259-4-juraj.linkes@pantheon.tech> Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-ClientProxiedBy: LO4P123CA0670.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:351::16) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|MN2PR11MB4663:EE_ X-MS-Office365-Filtering-Correlation-Id: afba60bd-b580-4fd7-da1e-08db4d52eb1e X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 52rqlp15miK/UfXAaI3mpBeULv3Sv2iOeG4vMndJE/ZGpgxvCTtVRNJBD0WlZgcgRXRDcFtt28vtvhtmtzetYt3eAloJbj8lywmKeD4M9mbIMYZWnCcPIs9bz+M7Us2FGUUphKDS7U86VftjBhvtIMYInh1Ivq3A0lkIIDBq9GL4IUTCTgU2QJiQLx0yqyCGMBsQfHufr2EPZUFbdGrlaj/nS0thB+jFwLK8cluF+++RqxX0gNQ3mAherSFPCz0ecHNyUihgvm9LbN0GTF3s5b5g7v58BQvxyr3ftCHLMuVMwwMMuRQfwZt2nQa91T3PhhshSZFFhO4wGi2Fk0AmbtDcoi/Gva4OQOZoRdtFg4uoFeDR0pwV8UbVk2ZtLOwKDll7lYErWgtAc3ij72AwSnckzIWqel0G2MZdgVKM1TbXKltlrFzgLMtkoWCSUUUg6v8F5KdTm+27jx5Uvbw7ytjvoGK5o4Rit4TaVyz+AZk3CZ2LR7sBPeSZWz0EhOhoG32EsTiv9ZCO2bBvMAvPuJ2eivAn2yxUlXkF4XoJ+ps= 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)(396003)(39860400002)(136003)(366004)(376002)(346002)(451199021)(66946007)(66476007)(4326008)(6916009)(316002)(66556008)(38100700002)(82960400001)(8676002)(8936002)(186003)(86362001)(966005)(26005)(6512007)(6486002)(6666004)(83380400001)(2906002)(478600001)(44832011)(5660300002)(41300700001)(53546011)(6506007); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?U0FleWhGbTlaaysxTUVOU0huL3FuSFcyWUdBV2gyLzhGeDQxRWJEYWFFbmJX?= =?utf-8?B?VmtoZHVoa25YczVZbnQvaWVBaDlVLzNxV2diUC9QcjVLNCswR2xhZ3VndEo5?= =?utf-8?B?S2p4akJISC9MdHZvRi9QS3ZtQ2YyOHhDZWM0R2JTNjdXRU54TklFZHBFcDdU?= =?utf-8?B?ellZdTJFSDJtcERPZG9lNXNvSXQwWjhaUmU4TEtsSlhvL2o4NndPbTZpK3BS?= =?utf-8?B?bTNqM1c1OFU4K1Q0MVNBY3REZm5HaEVlOE8xV0g3Vk1NRFptUjhqWHNvOEk4?= =?utf-8?B?ZDJHZGordUh1UFJoYnZwcmVzdkMrdXNQQ2poUVhCQkxsZ2xVajRKa1JodS92?= =?utf-8?B?RG14dEpESEpFSHBVU0lWVzc0YnFINTNhNGtjcWYvV2JwT2xqNkRqckNaMVFP?= =?utf-8?B?d01FSEE4TlQreW1sbW9DWjI5dk13bTA2WlBNUmdwWW5aTVVnMmxVRTB1a2tl?= =?utf-8?B?VFdaZGxmU0ZJd0NMSWFtVmVOVDRDMkw0Y0YxK0RUNjhtdEJCTXpWQXlGdmVs?= =?utf-8?B?cklyY1Q0QWtTQVJTQlBkNTVZYkZ1dHZaVmhCUHRkYjhjQmFZQUxZL25QSlEv?= =?utf-8?B?UmdKU2Rna1hjeWJEMWFtNU45bkcvUXlISVkwWFZaN21wREdSYmdFczh2K1cv?= =?utf-8?B?OE96Q0ViSVFoZzM5RGxYVDZrUURyT1FMY0labGZ3NkJEbHNSWUQ3TnVJd28y?= =?utf-8?B?a1ZjcG1oMDU3dEs2dXVuWklURE9kYmw3SXpUYVFKTU9sY3dRNVN6REVQa1VZ?= =?utf-8?B?aDUvSkhXemx3YTY5MFZnVEwrTjJ0eUNGSUtjSUplcU1pU3FDYlEzUDdoVTB5?= =?utf-8?B?c2VHdCtDTVpVcHNBVkZpU2NPN2pwVHhDMEdXcFpWVVJSK0ZMdWxUa2drTDRS?= =?utf-8?B?UFVyNDFWY0pTY2tUTm96Mm5uaFg2b05aUC9HRFZxa2ZMSkh1a1VQMW0ySFlM?= =?utf-8?B?OW8vVk1EWnJsbUV6NUJ0azNGcWdRcndMQmNRQ0gxUGRVQ3QyMlREN3FpNVNT?= =?utf-8?B?ZlRXVkRzbWJlY3Juam5GeWlvWks0V3RLUHdBblJScmRPb2RGOS8vMktHT1pF?= =?utf-8?B?VHdGeXZvZ1IxM1lwTldYR2dYNjhlUXBpK2dJSDFPT3lIZWIxTDNMWUZRR3Ar?= =?utf-8?B?M3RKajVGRUxHNHhmZjZyNDBBcUh5Y3JoejFRUkplYnBTK3BHVkZBaWp2REpD?= =?utf-8?B?Z3p2S1dhSFNDNG1yR3NGdHZTMFRKRkU0YktaelFyRU5mbzFWWnZrMDE3aThT?= =?utf-8?B?S0hBNUxIbUZhdUVFbmNNTWdRMVdoVnF3TTB5VGVJajhzODlDMG1JMk5McURZ?= =?utf-8?B?S01LVlh5SU5IMEdCaXNHY0VwcUxMVzBOcVJKdkdVVXJTbHBUNTZzYnFFL0FB?= =?utf-8?B?ejAwaXZ1bmx6ZmdlWFVJTkNLUnM1TFRBZFVwdW9GenFNTmVINVBFZ01lSUxO?= =?utf-8?B?V3M5N1Y5ZlFnazJhSU41cVJyZ2hTOTdMVE1qajUzWFIxYjNwcllyUGRCeW5p?= =?utf-8?B?M0lBMFpPNWRBOExpa1hOemR0aHRScE9QeUFITlZNd0xpN2VGS0Y3djdCcVNY?= =?utf-8?B?VVZ3R3VldjRXWWV0OVVxYk5XejVGMDBKcU5hK2R3d0NmV25lM0VmaUlkRVRp?= =?utf-8?B?aEdYWDFwQ3pxd3hRbWwvOEJ6RHI2K21pMkJrTWszWERCQjU2cUZnZnFiL2Yr?= =?utf-8?B?UWQ0REMwV1VGT3lWaXRzaTE0N0hqbnhhN3MvOTB1c3FCR09JMnIrNkkvdnlI?= =?utf-8?B?aGUybzZ5ektocXI4czZYOXJYcTJqZGVnRm1kcmRVd2pXT0ZYcGpXWWg5QjFr?= =?utf-8?B?UkJHQ1lxYm9LUzBidTE4UVcvaTIvMk1rMUN3VHBlMmVOb1hiamZPYzZ5WEFa?= =?utf-8?B?UDF0SGQvRE5NUkQ4Q0x4UzFsSGxOcUtXZFQ0bGpLejNJZUdjNkEvdkRZOUVu?= =?utf-8?B?L3NudnR4d1BGd0dTam1PM0pBdzNyMDE2UERtcjljMFI4SzZOczF2Nm1ua0hD?= =?utf-8?B?bFduYmsxVWtJbW1YU2xXQ2ZOSkQ3NU8yWjBQcHRaeHF4ZGRHMDZRUGU4L01L?= =?utf-8?B?clM1cGtGRERmSmkwVDBGS1F1ZkFBdlpVM2c4cnZhTkpHZXg3S2ZVall3UkVw?= =?utf-8?B?c1BHTU1VWmMwdmFMQ2o2ZXlPU1NMZis0d3NKS1A3Rmg2U3h2QVo3NXNmM0Vr?= =?utf-8?B?a0E9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: afba60bd-b580-4fd7-da1e-08db4d52eb1e X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 May 2023 10:24:33.2826 (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: QIQe1SrDxzrvAWZ9WxFUli2ryfG6QRcwnmuQl1S86jSFC4Wg1S3HoA0IzU3jreRoSKU7QdPMQx68U2SsoIcnzrxZ8NmYkJBKCatF/1DYBeQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR11MB4663 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 Fri, May 05, 2023 at 09:53:50AM +0200, Juraj Linkeš wrote: > On Thu, May 4, 2023 at 2:45 PM Bruce Richardson > wrote: > > > > On Thu, May 04, 2023 at 02:37:48PM +0200, Juraj Linkeš wrote: > > > The tool used to generate developer docs is sphinx, which is already > > > used in DPDK. The configuration is kept the same to preserve the style. > > > > > > Sphinx generates the documentation from Python docstrings. The docstring > > > format most suitable for DTS seems to be the Google format [0] which > > > requires the sphinx.ext.napoleon extension. > > > > > > There are two requirements for building DTS docs: > > > * The same Python version as DTS or higher, because Sphinx import 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š > > > --- > > > doc/api/meson.build | 1 + > > > doc/guides/conf.py | 22 ++++++++++++++---- > > > doc/guides/meson.build | 1 + > > > doc/guides/tools/dts.rst | 29 +++++++++++++++++++++++ > > > dts/doc/doc-index.rst | 20 ++++++++++++++++ > > > dts/doc/meson.build | 50 ++++++++++++++++++++++++++++++++++++++++ > > > dts/meson.build | 16 +++++++++++++ > > > meson.build | 1 + > > > meson_options.txt | 2 ++ > > > 9 files changed, 137 insertions(+), 5 deletions(-) > > > create mode 100644 dts/doc/doc-index.rst > > > create mode 100644 dts/doc/meson.build > > > create mode 100644 dts/meson.build > > > > > > > > > > > > diff --git a/dts/doc/meson.build b/dts/doc/meson.build > > > new file mode 100644 > > > index 0000000000..db2bb0bed9 > > > --- /dev/null > > > +++ b/dts/doc/meson.build > > > @@ -0,0 +1,50 @@ > > > +# SPDX-License-Identifier: BSD-3-Clause > > > +# Copyright(c) 2023 PANTHEON.tech s.r.o. > > > + > > > +sphinx = find_program('sphinx-build', required: get_option('enable_dts_docs')) > > > +sphinx_apidoc = find_program('sphinx-apidoc', required: get_option('enable_dts_docs')) > > > + > > > +if sphinx.found() and sphinx_apidoc.found() > > > +endif > > > + > > > +dts_api_framework_dir = join_paths(dts_dir, 'framework') > > > +dts_api_build_dir = join_paths(doc_api_build_dir, 'dts') > > > +dts_api_src = custom_target('dts_api_src', > > > + output: 'modules.rst', > > > + command: ['SPHINX_APIDOC_OPTIONS=members,show-inheritance', > > > + sphinx_apidoc, '--append-syspath', '--force', > > > + '--module-first', '--separate', > > > + '--doc-project', 'DTS', '-V', meson.project_version(), > > > + '-o', dts_api_build_dir, > > > + dts_api_framework_dir], > > > + build_by_default: get_option('enable_dts_docs')) > > > +doc_targets += dts_api_src > > > +doc_target_names += 'DTS_API_sphinx_sources' > > > + > > > +cp = find_program('cp', required: get_option('enable_docs')) > > > > This should probably be "enable_dts_docs" > > > > Right, I overlooked that. > What do you think of the implementation in general? I need to download and apply the patches to test out before I comment on that. I only gave them a quick scan thus far. I'll try and test them today if I can. /Bruce