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 5A42C42A6E; Fri, 5 May 2023 15:29:04 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id D4BD6410EA; Fri, 5 May 2023 15:29:03 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id BF31340695 for ; Fri, 5 May 2023 15:28:59 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1683293341; x=1714829341; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=/9SBcY4rUK9+sDIbplw6LeZU25Ez9H5GCCIjICmOITg=; b=EUDh3VV+YhtORobh94uzfW4kyAqNn35l3Xt7yrKZ46fQ3hqkjZroYgoY ibC4wf33b9i6BHVR8Jq58XDqeBl7IYn4A4hsJT1SlY7fDQ2Sk4soqZhrZ QghW4wZL3hJq5urqS1lKpcA7yOttJbwZdSVxZXblzCHwpUj6BvYD6R6De NAx966FkW8+DFZlwwvRwK1CF6g32R+rN2lCvzW4t+EOyHR+zMLca5Mjhf zItNjGrfu5Fxmk3G7XhIgChmRiWYVf21ACbjZrDFnIWGHnB7HXV0FrIN+ WmUhfNKHNXcaqhCfsyGZo/A/uyqEk9yPulw1mZDafI4TeViBEIz/arlZ8 g==; X-IronPort-AV: E=McAfee;i="6600,9927,10701"; a="414743446" X-IronPort-AV: E=Sophos;i="5.99,252,1677571200"; d="scan'208";a="414743446" Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 May 2023 06:28:58 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10701"; a="647856167" X-IronPort-AV: E=Sophos;i="5.99,252,1677571200"; d="scan'208";a="647856167" Received: from fmsmsx601.amr.corp.intel.com ([10.18.126.81]) by orsmga003.jf.intel.com with ESMTP; 05 May 2023 06:28:55 -0700 Received: from fmsmsx612.amr.corp.intel.com (10.18.126.92) by fmsmsx601.amr.corp.intel.com (10.18.126.81) 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 06:28:51 -0700 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) by fmsmsx612.amr.corp.intel.com (10.18.126.92) 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 06:28:50 -0700 Received: from FMSEDG603.ED.cps.intel.com (10.1.192.133) by fmsmsx610.amr.corp.intel.com (10.18.126.90) 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 06:28:50 -0700 Received: from NAM11-BN8-obe.outbound.protection.outlook.com (104.47.58.168) by edgegateway.intel.com (192.55.55.68) 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 06:28:48 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=fkxQHHahQ3PNSGJiwWyaW+XgzukNzWHvLiAqvCcAV/04gWvsxL60/IaZdoX3XDgFwTpWjUQvAjqKQQYkDv+GShKbbcT8fpODoboszOOYNx1kvl92VnTvcZhs2s6C+ouR/X6mSahJGd30VYcZK27H7j2P4mMurCtAt9ZaWO74LwuMh/bKcilhAWW9KNa+lhYZ4mSswES460PVIf/vK74J1JBBqzjWKy5h0+L8AuQxCwoF9957/UcHYG84bT4fiJtYMSZ/83UDv6VJDn86wbdLlV7s/EJlPAF/tdL4YsFZcOHsy2fQsRP8CfVtqsCujKo8aWUBypMp3d1YVwN2YYuJZw== 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=QQSyRnO9DTf8bO7iNXmfe2N/PI3hsWnUGm2u6D+onek=; b=fXeYePCOG2O8VkhUhboLTDX3f2fi5+CmseXd+vW6K9WIQm7KuDqxg3TG0eZZ6Tz2ShqGQyYomlmEqGDsCJhZfE4itzRvKl68NrZlfHZdejij100etYAzF4ezQO+u0nJ6kdu3UBT3ylm5tw8kyncW6rZX8/WhoWJHMLqZ8GGYkBRcgPnUEYO11BB0bfhbX009rMOYOcNyXwqXIAu1qKGYDkTFzrWzd6ZgdEDGwldoFkia+8ZzD0QpROuaFh4wHVEe/hPLqOddCv0Sxr1oG3cVQByizdMTP5MS2ZTXp4oD4UEgXvRK1HGQPp4d0l4LURMIgYz63HVrcBqrkK0LCRD2bQ== 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 DM6PR11MB4721.namprd11.prod.outlook.com (2603:10b6:5:2a3::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6363.26; Fri, 5 May 2023 13:28:45 +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 13:28:45 +0000 Date: Fri, 5 May 2023 14:28:39 +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: LO4P123CA0511.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:272::12) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|DM6PR11MB4721:EE_ X-MS-Office365-Filtering-Correlation-Id: 7ca46907-07e6-4e0b-c98a-08db4d6ca6c6 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: dJsC55wsGNj5TUAfXChn9Vq//kkMR+kpYmvnUFbXg3Rc099/MAT55qWgsUX55SAuwzz2h+bVKZM8678WZUkm6ftkRawhEZFtnRsdC487RAOaMd4zKK7XkHxR9whSWD952+dh6AZ+VbNsYedD9bytFjexq5PATrY7b00kwv6zYz3bfhCG9G6Ho71BmIb+Y20+DO+cf1ltCUoanG7SdTCJtYlFSntPIB7KpcR4Bl//1FAE15xQzo9q8gQlaa0MU68lasWcs+noVTHMn1H3QBDW5yXESby0rhdTiKWch1rws3fL1R5wzK57tqAkqM+XD104QJXMnhOTCpGGlzUQrSUIR4llpG0ekSerArs4CQzbJb/o+CwxbhcyLaVWIT7Th+hrRzc7G+Y8EWCRdsiFjf9xS9runI9gmU9bpavxgbc5oAWUeKiaF5s1oWKzjIuAV1RjHZhK77hpq5OJoagybY6s1uGtNei04F09VaMwO3aE8uU9XNG1Ue9b61P4nL0qoXJBW4Kn9gAFs9llQiOkK00AHD1l8l8sGN60gu1PBdAuH9I= 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)(366004)(39860400002)(346002)(396003)(376002)(136003)(451199021)(53546011)(966005)(6512007)(26005)(8676002)(6506007)(8936002)(2906002)(83380400001)(44832011)(4326008)(478600001)(6666004)(316002)(6916009)(5660300002)(186003)(66556008)(66476007)(66946007)(86362001)(6486002)(41300700001)(82960400001)(38100700002); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?RFRzL0V1OXUrTks1MVI3d3pzNy9UNEhuaEtmd3l0bDRxdkNDeUw0aWJPRWY4?= =?utf-8?B?NkRGaTZNVm11ZHFYWnlZS21iYzR6SHY1N3Nla3gvcmlxN3E4M2tMeGUvbzds?= =?utf-8?B?LzUyeG9hK09YTGUzcFROZUtiVXRkQ3hseVRVRTRyYU4zTy90dFFMWm5UTjdt?= =?utf-8?B?WFRDRjdhQXUyVUQrUnkxUTl4MXFIeGJvaG9IQ1NZU1l0SXZrNnZQZnB0cXRB?= =?utf-8?B?N25ad3dvWS90WkJWckhMSjlIajBYT2ZUbkcyZ0NZeDhQNDY0K2M1OUNtaHdJ?= =?utf-8?B?T0l6QU00cXZoT1Jyamd1UlFjaGVWclBYeWJQUS92ZGRpQk0yamF3VFo2S1Q3?= =?utf-8?B?SjFpTmNFZ0NTZm5lOENMclZ1eUdnRG0xakFDc3h2RzhKQjJpR2lqMks2eFo5?= =?utf-8?B?cGpybTduS1Njc3VmYmhpdC9ITlBOeElTTTNQenB3a3l3Ly8rbEpUVGh1ektC?= =?utf-8?B?aEpiQnF5SVhLNzBoZ2QrMjgxYm5YUVdOcHpMemF3ZlRrd2dXcU1aSnY2aGVL?= =?utf-8?B?Q1FteVNtRmlvTUtXQ1Rla1BYRGxUSjJVb05qUms1eCs5WUh0R3laWVVoWm9K?= =?utf-8?B?eXZVemh2SmdLNTQrVHI3eFhoSnJacllpUTJkQmhkMUFwS3c5dVpLeWY2Ukdv?= =?utf-8?B?ZzJKRVNiN09uUHRRVGhxTEZxNFRzRlp3WE5ZbUlqSHJRNTRESDdudXA0UjF2?= =?utf-8?B?ZmMvZk9LallhZkxhU0hmT29wdzJqRitxV2pibmRuMkRSR2hIaXZHTWc2QXVT?= =?utf-8?B?VERSTXNTRlBDeFNQRVhRK0R3NXFBclF0M2RIN2ZOR1JYL2dUcmtVUW9RWG56?= =?utf-8?B?NHZxWXYra2VOSWJjYWJJSXIzREhEN2ZweHQ1WForVnNwNThrTGl2MXlzUGh1?= =?utf-8?B?UGdlZ2hpMVA1RVdkclNyeWRnS3VNVDhySllxNkFZRzhrZEhmU2pqMlNSWU1B?= =?utf-8?B?QlhaenI1T3U0N21mWmZ4a2VuQ255U09kbm5ubVBVZm01aUtyTnJCRTVzbEds?= =?utf-8?B?VEZmZUNJcWhqNWRtRVpRSy90WEdHSGk2Y2hubjF5MlRKRDQ3Smp1RkZLbE8y?= =?utf-8?B?eVpBVUw3eml1UjdpVXdvYlY2ZHUrV2FyVTE2YWp2dkovU2JWSmhIMDRBZkpQ?= =?utf-8?B?Y2RxUWE1akUwY25RV0g4RnVSNk9HU2x3Uk9NZWdOUDZtUzFwU3FiSzVkNVZL?= =?utf-8?B?MlhrSFhJK2Rrc1NMSGd4cUtIVFhGcGRVU3JCYURVSTlYeDZjNGpXYUVoeGFa?= =?utf-8?B?SWlYV1NIbHpiOUo4dmRRNURrVkVubUFZMkRvV09CQ3lrM3MrSGZKV1RKVXNG?= =?utf-8?B?Z0VmYzQ5cHBaU3IvZlpIV0FBbHIyZTZTeFRuaEpSOFlqS3djSzRhemdkT1NY?= =?utf-8?B?bUhIOHJuWk9JT2lsVHQ0Vm54YUZHRldKaEo2VGxBZmY0MFhpQ1JYNlFHcE90?= =?utf-8?B?aVB3NUsrMmdCRERwclRVV1ZWRGJxeGVYRUc3dFdocUIxSWdSWDQ5Nk56dUgx?= =?utf-8?B?N0dnWmpMUWR4ZzRrSnhYM0xSYnBNWVVjYnFadXBudWhRdU5rNDRYYzFsVnRs?= =?utf-8?B?OVhiMkhsZjBWY3BJMG16QStJVFluWEh3RVcyY3g3WVNxNytPZkRnNG4vTCtI?= =?utf-8?B?ajFVVURZL1lhL09jYzJQbzFMODBtSlA3WUlFYnFRTElRQTNhcnR2b0psZlEv?= =?utf-8?B?K05HbklzQSt3VU4wQjNYS3RBT25RbUJuMnlocUpWR1llTG1udjRxOUZieXU0?= =?utf-8?B?VTcraHNINjUxT1BFL3lNL2ttUDVJQytjQjVoRlF6dExaSTZjK1pDS3hXMC93?= =?utf-8?B?a0U4dHEzbExMajdaTjgwMVE2WEJyU1dXQk9hQk41UmxDaXY4WXkrUEJPRW92?= =?utf-8?B?aHAzdUlPdllhczVXV1pBNmI4WWVvNmU1aHBsa3kzV0RtcFNuVnQ4SGp0N21o?= =?utf-8?B?N3VsNzUrdkJpdzlyeUNXOTA1dXZKeXFVZ3piMW9vYUNrMGliL0JtUm1KeGNY?= =?utf-8?B?MXRDY1o4TlVlemoxbVBESHdQWFM4UVRLbWNFUXdNMEUzWFQrbTRFYU9QSFJL?= =?utf-8?B?RTlIMDNwV21rdFFUNEgxaEQwdDZPakROZEdqTzRKK0xOZHVoZENsUHJJeEhV?= =?utf-8?B?L1MvTjAvL3ZVRE1JTk9hUCtDYUtEMldxdVpsai93ZGRpaSt0bEhJSUZaYklJ?= =?utf-8?B?OUE9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: 7ca46907-07e6-4e0b-c98a-08db4d6ca6c6 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 May 2023 13:28:45.4503 (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: cN0vGYbthsfNZXN7bow6iRPDnVmhTXgX7E0RH6BjFS7LF/G1unmA5FsSsJBy+fEDh6o4RXnIEX8i632o4pN03lHpJhBqBRXqVIYIbyPY5oQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR11MB4721 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 01:13:34PM +0200, Juraj Linkeš wrote: > On Fri, May 5, 2023 at 12:57 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', > > > > This gives errors when I try to configure a build, even without docs > > enabled. > > > > ~/dpdk.org$ meson setup build-test > > The Meson build system > > Version: 1.0.1 > > Source dir: /home/bruce/dpdk.org > > ... > > Program sphinx-build found: YES (/usr/bin/sphinx-build) > > Program sphinx-build found: YES (/usr/bin/sphinx-build) > > Program sphinx-apidoc found: YES (/usr/bin/sphinx-apidoc) > > > > dts/doc/meson.build:12:0: ERROR: Program 'SPHINX_APIDOC_OPTIONS=members,show-inheritance' not found or not executable > > > > A full log can be found at /home/bruce/dpdk.org/build-test/meson-logs/meson-log.txt > > > > Assuming these need to be set in the environment, I think you can use the > > "env" parameter to custom target instead. > > > > I used meson 0.53.2 as that seemed to be the version I should target > (it's used in .ci/linux-setup.sh) which doesn't support the argument > (I originally wanted to use it, but they added it in 0.57.0). I didn't > see the error with 0.53.2. > > Which version should I target? 1.0.1? > > > > + 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' > > > + I didn't try with 0.53.2 - let me test that, see if the error goes away. We may need different calls based on the meson version. Is there no other way to pass this data rather than via the environment? /Bruce