From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
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 <dev@dpdk.org>; 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 <bruce.richardson@intel.com>
To: Juraj =?utf-8?Q?Linke=C5=A1?= <juraj.linkes@pantheon.tech>
CC: <thomas@monjalon.net>, <Honnappa.Nagarahalli@arm.com>,
<lijuan.tu@intel.com>, <wathsala.vithanage@arm.com>, <jspewock@iol.unh.edu>,
<probb@iol.unh.edu>, <dev@dpdk.org>
Subject: Re: [RFC PATCH v2 3/4] dts: add doc generation
Message-ID: <ZFTg8BOE2ji5IPbb@bricha3-MOBL.ger.corp.intel.com>
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 <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=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š <juraj.linkes@pantheon.tech>
> ---
> 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
>
<snip>
> 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'
> +