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 9471142A70; Fri, 5 May 2023 12:57:04 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 20AA441144; Fri, 5 May 2023 12:57:04 +0200 (CEST) Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by mails.dpdk.org (Postfix) with ESMTP id 490A4410EA for ; Fri, 5 May 2023 12:57:02 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1683284222; x=1714820222; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=dU/J6FT2V4Ajq23C2xQnuZfswGWSWlKKskYgD9wMa9w=; b=lLhUYsPy7Q1dG1J870a8isrkfCvFzbJaHgK1EDehmyeCKNqe0IooVNYT gWwkeLGBmf5umTbD2MzEXU96EBFV6eZ6oc+P8UTIfCraxnbVLwCR3H8xq J1O6XBwz1ENlt2UAtGh6tli2wD3htxhNBe6N8B2Y7s7JHIcLdDsh6Rzea 1upYZfNqi+Se+hj7oG3X00+SmoVSR/DNkapeSi/OmJoGt/u6t8bp/cuEo fHltN2tkkpSiZQoB5jR7jDkzALG7/jPefC9uXClBjpGiWTHgbyj2tZAra pIu2W50/+h7uVF2ics5YZgmYgLA3o7sZ5/7bGJOvVJtyMyZibhSee6CVb A==; X-IronPort-AV: E=McAfee;i="6600,9927,10700"; a="338368894" X-IronPort-AV: E=Sophos;i="5.99,251,1677571200"; d="scan'208";a="338368894" Received: from fmsmga004.fm.intel.com ([10.253.24.48]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 05 May 2023 03:57:01 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10700"; a="767033709" X-IronPort-AV: E=Sophos;i="5.99,251,1677571200"; d="scan'208";a="767033709" Received: from fmsmsx601.amr.corp.intel.com ([10.18.126.81]) by fmsmga004.fm.intel.com with ESMTP; 05 May 2023 03:57:01 -0700 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) 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 03:57:00 -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; Fri, 5 May 2023 03:57:00 -0700 Received: from NAM10-BN7-obe.outbound.protection.outlook.com (104.47.70.108) 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; Fri, 5 May 2023 03:56:59 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=mtYTQb58E//c9Foir2nT2hXylY88ULxsoBZAJUz481hQVMEdR3RNhJ0vqEE8Z1lftV/R1Yu5cT5rxSpZWx97O144JHigHQTtmftcsOlE1u4LFCdIN6sfltB0CxXX9uuR7IxU+JWk4xaNRtyEzFq7ytE9DVak+emBUWXJqxuCX8rlo0E+hQ5GzM5oobUgwDzMx2i7G7z93KtAxRFwoaBCVj/DHTHz0dqkt3NBtgeqJYQIj+Ytyx3tpn2sj9MXT4LVR1CUdhr6toHEVDkgrQXJVQmMmOcOkPkpVUZPPpg1LK/g70IWQFm/q5Lqod4WHyIBL9eT3FwyB7f0eejMWt/EvA== 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=tLti5YGh20kgfhrVcajuhkFEr891HMuJ99Rjo1y/YOM=; b=Gtc0N5NlLtws3scgWe8cNKpJJiRtoRLAaM/lu89SIvgK+IdXSHEyt3WBJko7WCtMt0A3890+18IycjtHHoEDDQJwtnLlKMQKqimG4laR0Au+6KQ/TthNia4OijOeAdZi51N94VcQATnlr6jpEmlWq13Cbcj9RMRxy0xgWszUdu4uQpYnEPnDjRNat6ej91aCqj53jE8Oec7WcODYFtNLE8Fw1N60xqcKe7bvegull7JAcv2+axw1m2n4guKACamQtJpi2dSxw13IqxT7yad/gDdt5nczfOUiZF8ByyB1E/XP4DooASo2Y1UyRqbjDrYZC91wXdRGId4fbXuWKIt5Vw== 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 PH0PR11MB7423.namprd11.prod.outlook.com (2603:10b6:510:282::9) 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 10:56:57 +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:56:56 +0000 Date: Fri, 5 May 2023 11:56:48 +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: <20230504123749.1417259-4-juraj.linkes@pantheon.tech> X-ClientProxiedBy: LO2P265CA0473.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:a2::29) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|PH0PR11MB7423:EE_ X-MS-Office365-Filtering-Correlation-Id: c89cf432-4ce7-4d5e-086a-08db4d577124 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: culZ9Z276zTG/gb2RB+qZNgAAq4MX+D9wOz91GPJNS/xSqiFUHxgfB8jDiqCZbMuweBcmDDgiyIiMsJ2hjFheEUMWAPP13eVu4Z8QxnSgqEJLpPaH/3DGeb72mGorb6Z5xNrVvcy/0JkFC4A4Bk9bLT9HRvhcImkjSVPvQ6pmRS/zTpwCbCz3133DepfiZmwdKYduIqEMsJbyELj+D/+1vwjTJpMbZmIXkk/izKxYdQ7XTpvgI+fWZQKK990qbuq7AiZXU5hJ/658y/ZSboC6rifXyF6v1pRySh4eEK0KbKbouQZ/U29QHXhn2WIFSUF1aJt3ZjGr6UKHdB5WLYx4xF+9EJIFTTdWfyudfm6Yp7qExfTYYOGB9/fCTv2PcSdnMNYkPZbNzwskuJD1iHZ6/c07ovak84Sew9LpEsCvXOuLhVVoitqReyUAI7nStV7ncd4kCKuUdFIcAIlVoztmRy6gnFNHc95vAmJt6AcbSIV0u9o9lAzliLC/1l+ksy0XLyH6XyhrhAgF092j5RDGoZpKAxSgrCQIFHL3qe4SPg= 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)(136003)(346002)(396003)(39860400002)(376002)(451199021)(966005)(6512007)(26005)(8936002)(6506007)(8676002)(186003)(5660300002)(316002)(66946007)(66556008)(66476007)(4326008)(6916009)(6486002)(41300700001)(478600001)(6666004)(82960400001)(38100700002)(86362001)(44832011)(83380400001)(2906002); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?T3B1YW13dEc4ZHJZTXZOUExmQkh3TmVCNmZnM09KL2kvT3JtOU5MWGx3cTlp?= =?utf-8?B?cDFOdy93VEczZHUrRm9JMGowRndocTdFNmZlWDVBekJTOTYzMm92MVBJK3hY?= =?utf-8?B?NmdDRjBxcXVoQnJ1SEJ4aEx4a1JXYjdSb0RlSDVsWVlKMEpsVTE0SitrNFJY?= =?utf-8?B?TGE5U3ZHZTF0WVpYZE41NFdmbkxRUGg2SFdNbjNGQlJCUkhjcXI4UHdBMkhK?= =?utf-8?B?amNHVENJZk14aVlvV2EzSHk5WHdzTVlwS1JXWXZVdjl3aFkrS202dkcxamRQ?= =?utf-8?B?cUY3U3NZYWVsc28yRDNoWXRFYlVncHpmUHlsellaczBDMGxFc3BsYkc5dXBK?= =?utf-8?B?QS9LTHJXWFhGN0N0bXg5N0VZZmxQZXlXTXBoZTFFSEtXY0xGRThGd3ZXeHU4?= =?utf-8?B?M0JoUXpISmxYMWNvNitWNUJCZno0QXNWV1RrYllvdU4yeUhoTjBoNFdVdm53?= =?utf-8?B?ZndXQ2FLdSt1dTBCN1EyU3RGTXpsMTNORlZhRWhQK0ljM3dOUVc4Tk5MRlFq?= =?utf-8?B?eFVDUXl2RlNmS0k3RlJMWlFvb0Z0SW9rZWxueWg0QXRuRGljU0hFaXd4b1ky?= =?utf-8?B?M0NtQ1VrU296YitWZ3BOekgrbEtOUkR0c2ZqclZRSTd2eUN4ZDNrSS8vd2lP?= =?utf-8?B?ckY1NjRaNW1EUXpVczV4NFBkTU1hKzFray9WV1locmxKQ0RuYW9QdFk5ckZS?= =?utf-8?B?WU01akRIOXF2WTZkMDRCVW92RGRQdU1zWTNsbmNsUmpUMWVqQmlBZ1E3Mjhn?= =?utf-8?B?K040MllCaWtpVlF3UDExaFJmdVBHQXBBcEFDN3p6QUMwUWRpbnMrNzVBTDdj?= =?utf-8?B?NEVYemRXRmpFVFNNZ3lrU09HM0YzeEM3VSs3NXBZVzF4OUpseTVEOU9jSmtJ?= =?utf-8?B?WWI3TDl4UUUzRUlkWDRpY0hidlUyWHJTbmF1OHczUGVmYnN6UUFweXpjZFF5?= =?utf-8?B?V3FHZVhWNnVIVVQxZDdwUUVUQ3ZkSVJLdE02eGJTckY2R2o3NU8xd1VFTVYy?= =?utf-8?B?SEhXbC95ekF6emNCaVhXQ3c3dER4WURqQjFzOXBJSGM4clQvakhxemNTZ1ly?= =?utf-8?B?SE50Z01xTjlMd09jam0yTm5wMFlRdFllNXNRYlRzZWNqNG8vcDJwTys4VGlJ?= =?utf-8?B?cFMyd2d0NWowM2U1K21YUE9SZG1qUGdlZWI4SHFvc2Y2SkhjM3ZXcXIxMWlp?= =?utf-8?B?UXRjbEtvdlFlSHE4YzlReHEvandiR1pkSERDMWk2NDNHbkxaQUdtbitvWlFa?= =?utf-8?B?V2tEbG0vMHlCK2hNL1FTYk5vaE5tVXFsWDhEYWJYV2lOd3pQRDg5dmhJdm5G?= =?utf-8?B?TENNSUhQc3ptamNFU0dCbmFqT1Rnb09GNmV5emx3dG9jbDZCOVV3aVNDZ2dX?= =?utf-8?B?aDJ5YlJsTWhaVVNDVVNaN3V6bkpjNUVTblZ5UFB4eFZPcW9POWpHR1RzV1NB?= =?utf-8?B?ZC9QNVowRExMQVczc1dsMmZhNGFNV1Rsa0FJVGZZalJhaDRpMThrOFlCSFZG?= =?utf-8?B?RDQ3Ykl6NjZXZ1F1Sm8zbzlXd0J2UkkrUUtGcXRYS1RhN3FvNmNkYklCcERv?= =?utf-8?B?N3ZCaWY2cGNGb0pmN1RHbyt1QlhFU3pJNWZ0djJyTHF6WTUzcTRocHFKSWkv?= =?utf-8?B?UjhGaTg0VXUwRThLWThDQ1RsNDBhUDByQndXelRZZGY1MHFQeDBuRnFkaTNN?= =?utf-8?B?YjBxc09RMFp0TmdPdk41em8vMkdFeEVqTTAzVDR6S29wVFd0RE1NUlhsVnVV?= =?utf-8?B?YjNtZ1E1ZG1uR2lBOUVDMnA3QXRwSnY4YjRxenZqQ2E2YUxVWUNUcDRhY1NU?= =?utf-8?B?SktUUXV0WUxRTlVPOCt6K2djTHgxTlM2dkVkNlV1bEQ5LzhISHpoSVRxSDFh?= =?utf-8?B?SXFHR0tRalpQdWF5VGQvUThicVdmNnFkNXk1T2FJc2tUYTFYazExZ2t3dGx6?= =?utf-8?B?UHcxNkgxMW1iUkFjVTJBTGJkM0JmVFhtemw4b3dTajQyOWM1Y1J3QWg0Ujgz?= =?utf-8?B?VW1BNmdCMldUbnNBZFpKSlJOSXZoMWh4d0dBYmNSYXpQMWNzZ0dYRjBBTlhq?= =?utf-8?B?TlNqR21nbkMzME92NzJxZFc4ekZrSzZwYUVqc2lqWkFPSjR2bTB4NkpaYzFK?= =?utf-8?B?Z1VsVkRHVXZLVGxKelBwV0RqZkRVT085NUVxREdFNFoxM0JENmtzNmUvNTln?= =?utf-8?B?UGc9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: c89cf432-4ce7-4d5e-086a-08db4d577124 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:56:56.0795 (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: sSXzWOjPHLNIzGKItiZpD9BF/OabDGTv7eXGpMIjj1PvCV2S8R1xdBHa/ugNx74A4UJA7/+ij4xYv+6aekki5APkbqd+V4w1cpmDgkb+HcY= X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB7423 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 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. > + 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' > +