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 55A0F42AA2; Tue, 9 May 2023 11:40:48 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E0827410FC; Tue, 9 May 2023 11:40:47 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id 33F5D410FA for ; Tue, 9 May 2023 11:40:46 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1683625246; x=1715161246; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=KmKmiy2wEd3pqSxNZSAHk8I62VxS2vCApiExeKBILr8=; b=AE44z9Ux+ku6WDaHAvIKS6GBBo8Kg5W5egSW6HWAohRBqgONNeD6stje yr34YoqA2u1LpqhdIFP9hp6FUM9XqtoXgN1ome7t57k9ERMzNW20I474o mLySQuSPXNUtjtUBf1N1RxryAdHePJ7IYQZqOtfKJLC22NItI9q7qR10S uGWUkIBaKDmkfIKV6j3kxTCr67DKP5AfmP8BhsLQ4KXZpnpbqNJSxMMHf LjytLgLbpp43SzLZuLbwlSTU4aLVfzl684mZE3D7w0DtJJGRGyeOSVEI5 cikw9eYfYWkNLS++SdK+KRZMAoIedSggiu6eGRjJfYK0I+5MLMFpItKVv g==; X-IronPort-AV: E=McAfee;i="6600,9927,10704"; a="352937143" X-IronPort-AV: E=Sophos;i="5.99,261,1677571200"; d="scan'208";a="352937143" Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 09 May 2023 02:40:44 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10704"; a="1028745122" X-IronPort-AV: E=Sophos;i="5.99,261,1677571200"; d="scan'208";a="1028745122" Received: from fmsmsx603.amr.corp.intel.com ([10.18.126.83]) by fmsmga005.fm.intel.com with ESMTP; 09 May 2023 02:40:44 -0700 Received: from fmsmsx611.amr.corp.intel.com (10.18.126.91) by fmsmsx603.amr.corp.intel.com (10.18.126.83) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.23; Tue, 9 May 2023 02:40:44 -0700 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) by fmsmsx611.amr.corp.intel.com (10.18.126.91) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.23; Tue, 9 May 2023 02:40:43 -0700 Received: from fmsedg602.ED.cps.intel.com (10.1.192.136) 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; Tue, 9 May 2023 02:40:43 -0700 Received: from NAM02-SN1-obe.outbound.protection.outlook.com (104.47.57.43) by edgegateway.intel.com (192.55.55.71) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.23; Tue, 9 May 2023 02:40:43 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=gxgPacM5mjlHBC1OpqJGRJuFvxN9V/Fnfs+tEDEdsB81rTTj7ttlAYcX5h4ynXmdBAJzbbgmfHlLJuoPQmCR8ngTKJ0LZIAHPnoa7/oXRusIaxm7tKvy3tR/aX5RabTC702baGVyRUR3LzsPT8VtZtFAhUzw9LnHU+sW1Me8CwhKCO59YhG0g2090KPq105neBth7rMCP3MMSol0mRgHQw0jmO9ZNFkRoweBh5XTBmO3kX2i/CnOEv0zrzOQj+nkB1hWWzoB8GTPu2QWBCWVBBggDroP6smPTUZY6ZTHcOIIHSfZ5oeA6mVUKYA34ubMkEaDNTOC2HosH0UMChPjHQ== 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=R2U90JfviZrv9VTghxQ2yzERp9M25v4ClJdALNhBhyw=; b=MBox+KX7eDVviW4woyZVeHFP7XU37++ZVX7dv9QsZK/5DKbfIMDEND0y9aqcHunqu1UBbRwY02TYzMDowb/yW+Td4ZyQoroDWyFBPDPz5vonMylBA5eiBm8b2lQYiayHRJCIDvIxQelAY3I/ch1MEgVSCCwQMC8S74gOW+PcvSXqoORUExEqpDEJlioF58AalW1NylZpXcBTivUxnErqIFzFgzBkgOmO9ku+vyHPR/gs5B5KjQDKoUSNXEOhqSgApizqrunVTt4D5P2H6NSqIzzfG12/CqdrYfzKU/I24/uRC/Ok6ohmgnmSKT5meX3zkAGn62TrvDTNNh/rQBb0yg== 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 IA0PR11MB7402.namprd11.prod.outlook.com (2603:10b6:208:432::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6363.32; Tue, 9 May 2023 09:40:41 +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.029; Tue, 9 May 2023 09:40:41 +0000 Date: Tue, 9 May 2023 10:40:33 +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: LO4P123CA0420.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:18b::11) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|IA0PR11MB7402:EE_ X-MS-Office365-Filtering-Correlation-Id: 61c0f1e9-e479-4ccc-8652-08db507173cc X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: zID8/IdBOCctnElZhMhh0c4bRLP10I7ICoZEvgcSz0zYcu93qRm/r7+ZWTQcuyhvYmLCjenuC1JePbwcIdiUFjtNk4xO4SwPlbo4B7JqpgylRAP8P/nEI50QyMy947+Z+vmHMmoU8Fmr03WmbDqq5vP0is1DHqSzsxaf2hMuWwybmcpltxT5jgLCIfQjC+6QI5PtxW4qGaLySUViE+1W4SjHkPcuGC+gnOTQMJUz040DjFYRaBHvC0bdgMpAcMgQKLTOtHLE2bwb0aw2tVPwW6MUaLRETHPQ1GKB5k9wVuQV7gg/POZDC9JM/v4XaIZWN7tb03hTIfscYh02h1tzWu4RQZXWwBcwvLfzbqwX67m7Enp5pKkU33uH4eB9drQnQU/2vm8r1+WFY0lM5el8Hi5trMIXGXwj9DoXAqYo8INFsH0eILYtvxjdsSbQ74XzomlmSHRMBeGngZkv3ZhSq6dQjZwZwQQ3jAskaenH4KCEkG7v1RH/cQ1M0bAXWb4lHi/G0PnhzpiTIyorxEknEwkiZHE9Jy17KjjJiRgTBz9fGfbQFACssgK21LbgCh0wIunX+u/wMN9or0MoYxudrGIPdpief7r/aMNg/03i7uQ= 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)(376002)(366004)(346002)(136003)(451199021)(966005)(6666004)(6486002)(83380400001)(82960400001)(38100700002)(26005)(8676002)(186003)(8936002)(478600001)(53546011)(6506007)(316002)(6512007)(6916009)(86362001)(44832011)(2906002)(66946007)(66556008)(41300700001)(5660300002)(4326008)(66476007)(67856001); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?dXNGK01KcGZCMmc2SkVpL1NqZEtPRk14RnMrdVRZNU4rSU9Ja3ljQ1NBbzcr?= =?utf-8?B?cTJacGpqNmNraUltd2ZVUVRIYVR6bnFRdk5EclRSMzF4eTJVR3c5OS8zL0Vh?= =?utf-8?B?TVNjM1B2d0toOUFIeDROYXJrUDhWVUdmdXRUS1NETmZQc05sR21tZmFRUnNu?= =?utf-8?B?OEJPVlN0TzdncGVyWHhiUFVZbjJUTy9RMjk0TlU0MlREK1RBVnN6VTBjcENr?= =?utf-8?B?WHhCRnJ3K2RmeTBMTkl0elRlVjBkOWdPdVlKTnNvSGZ3UDc5aTBwaTdFbW1U?= =?utf-8?B?QzVjOFJJeGgzcHI3Q3U5OWZQRFdzZGs3WUp5V3lvcHBTTEpPMGdGZzYvajFs?= =?utf-8?B?Q0VEM2l1MmlGZXJMOUd0djh0M0kxYkxCWkFVZlg0S2YyV3hkY0hEK1BnbzRH?= =?utf-8?B?NVAzbmtQdU8yUmZVa2paY3J6cjlpSld6ZURTVXJDMUhxMitWTE5LU3pzcEJh?= =?utf-8?B?d3JkQy9DVHZSaWVjOURhTXZQb1FOUGdPakRBMHMrdC9WTjBpYWVGVndMby9Q?= =?utf-8?B?d0p2MUlSWjNwaWVtdG1RUzBVbitIZFg4UjgvK1dJUjNUZGpuWExLQ3NTT3F4?= =?utf-8?B?ek1oV0NrNERBNVBzeGNXWFI4enBXT1UrblhTSXlud1dlbXphTDZkU2wvblp0?= =?utf-8?B?ZnRGa0Rjb3FNOGthMXRTd2NUSGNlY2lWNzBYa3BWRUNza29PNTRnUHNCY0Zn?= =?utf-8?B?RWMvemlHSXltL0krZU9aQmRjSGE0Mk91aXpDYi9EYVE2QWNmOXJINzZJeDZa?= =?utf-8?B?V0t2c05ROHdXeHc0THZ6ODZOTmRhVFFJUzYyMEVpcVhFeGRKU21EUFUvdzFL?= =?utf-8?B?YlVqMDNjb1BTSTVoY2owWmFyZjE0ZE9IZzN1ZG9jdjNEQmNDd3FxRDRHM0JB?= =?utf-8?B?cGxoNGNhUU5EMFM1MTF2eWp6MHluVml4WllVMFRlVng3QXJUb1IvdFlqMFJ4?= =?utf-8?B?NjFENlpJWk0yMnpkSVhmY1VzOGpDZmd5VUlvUkcvVkgxYTVTT3ViQStyakky?= =?utf-8?B?MmFjeTZDeFNvUm5MUlRhQ2g3MFEvMXhsRDVyMThqc2pYY3N0eU1MRnpnamZE?= =?utf-8?B?b2tJbjQwTDYrdm1pUlBIczlJemVzNi9OcmxDa1UrdURCdlAzK1V1OWl6dzRm?= =?utf-8?B?RzlrdS9tbTdBTXBWcmI5Yk8xQzhkd3FxYXVrOXZuY0x1RmFlbjdBNkhtOW5r?= =?utf-8?B?QnVINW5JNU1zTVFkZlpIL3BRUzRrTFZXQzRRT09wZFlzdXU4QjZseXIrcFhF?= =?utf-8?B?dWsxZUVwYklRQktGNTA1UVR6RFoybTFnQ0dmSjNpQ3REdnoxWVNabEtXVmZH?= =?utf-8?B?TUZkc0M5OXNsQ1F6SFViN2JUNDFzbktDWWw0OFV3S1QvNFpOYW8rbnMyWHU0?= =?utf-8?B?L3M4czIzeWpVa041MElzdGVLaEZDU044VzNJR3NFMkdzTE5KWVM5RU9VMFhk?= =?utf-8?B?YnVqdEtoNGFsdWErdDFnTDlqYlAwd1QxZE0veFBhSzdWY0U2MEFLV2I5cmM3?= =?utf-8?B?VENyd3JCbzA0RE1odlpXUWFoakZuSitxNlZtZkh1aVNtajhDZmRXUmVWa21p?= =?utf-8?B?TTZITzdyeldHQ3J0a1IvbGgyOXR5NkRENThQUVZWaGQ0bmZSK1plZ3gzemdC?= =?utf-8?B?OUdVR2E3TXA2QjRteldzOGUrNDRpa2RwYU5weHpPQnFMMUpSc2JSLzlpakht?= =?utf-8?B?NHN3NmljOFpuczBaQk4rWHVoTi91RmdOQURLL2dWN3RaOEZLRTZvQ1ZxRUhs?= =?utf-8?B?cUowclNMcHlaUzBVVSsyZ0ZvZTB6T2F6bjUwWmVuQVBNb1Z6aHR6RnJJdmRm?= =?utf-8?B?Tm5aSmhtZjZEakIrVXNpK0lXdUpGbU9kMjJNRmk2TGRJb2syR2hQR29mQXdv?= =?utf-8?B?Y0JadUt2ZmYrUnZLUGJ4NGh3RDFoM2RCZUFiOFBhVEtwSCt5Sm9KcFI4NS9x?= =?utf-8?B?eHVZekZVSXNHUTlJaHI3YUpuS01OTmt5RlhsVUFURWthUlRoclRmcGNYYW5t?= =?utf-8?B?ZXUrd2d6a0Y2akUrOUowVWRSRnhteDR0MmF3OWxuVDVTZGcrOWFWU3RSMVZG?= =?utf-8?B?bFlyVllVYU1CelhoRFFmS0QyL0tndGozOUlKNEpxdzRZNGhMSmVuT3Z0czc1?= =?utf-8?B?ZWdQN2k5OVZIem5qWjZnNHdHb1lzclprdW9sbUJDUTREY2RHdlUzenRzNWJC?= =?utf-8?B?cHc9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: 61c0f1e9-e479-4ccc-8652-08db507173cc X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 May 2023 09:40:40.9331 (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: RlzMWixRzHWnWsgQ4CO9AM+MTfxJDxX7EwlKC0M9EzlEfZ/fw47lL7g9MuxXap5r18NT1nOAN14sIC7CGOTodcvFkRrBRrXJZkrrJn8fBnc= X-MS-Exchange-Transport-CrossTenantHeadersStamped: IA0PR11MB7402 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 Tue, May 09, 2023 at 11:23:50AM +0200, Juraj Linkeš wrote: > On Fri, May 5, 2023 at 3:29 PM Bruce Richardson > wrote: > > > > 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? > > > > Certainly. For background, I wanted to do the same thing we do for > DPDK_VERSION, but that would require adding an additional parameter to > call-sphinx-build.py, which wouldn't be used by the other call of > call-sphinx-build.py (the one that builds doc guides), so I skipped > the parameter and set the env var before the call. > > There are a few options that come to mind: > 1. Use the parameter. There are two sub-options here, either make the > parameter positional and mandatory and then we'd have an awkward call > that builds the guides or I could make it optional, but that would > make the script a bit more complex (some argparse logic would be > needed). > 2. Hard-code the path into conf.py. > 3. Have separate conf.py files. Maybe we could make this work with symlinks. > > There could be something else. I like adding the optional parameter. I > don't know the policy on buildtools script complexity so let me know > what you think. > If the parameter would be just unused for the main doc build, and cause no issues, I don't see why we can't just put it into the main conf.py file. We can add a comment explaining that it only applies for the DTS doc. However, option 1, with an extra optional parameter doesn't seem so bad to me either. Using argparse in the build script doesn't seem like a problem either, if it's necessary. Maybe others have other opinions, though. /Bruce