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 A7DEA42A5D; Thu, 4 May 2023 14:45:46 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 7D311427E9; Thu, 4 May 2023 14:45:46 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id 5421C410DC for ; Thu, 4 May 2023 14:45:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1683204344; x=1714740344; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=6uxDiUhv/uhZ2zc4WTCdZ3lUk/SFyWhxQlhUgNoB1WI=; b=l83mW1RsgbSYgTRH+zEf31pWo2Do7ilCu7ZCDQVlKxrXlXaoBUQOdcqw Pfqu3bA44EAzO+B9hVtJfvKjkPNb6q7/yw/yZdnDXkztI0LcW1uzYMnGz uZx5nG/3arWmtBW1XUheo2e/19yPDV/QJ4sPwZ0yohoioaaQn+lxAKpgN 2sz4OH+4m/Vn4nESmAZXjZWsDlmyOswOa/GaR+bYCvZxqREZYyGL9M3Wa 0BCRpz6rhZ+NBX0ulfSGcOPsvVj/OEU4m87iGSkIAPQ2bIQ+UZiFJMIgp VTzuUfzDfD5VT5oiAEDp52+ryGyvGG31Uc0oK2SArqMXHjlHt3q3fLGKA A==; X-IronPort-AV: E=McAfee;i="6600,9927,10699"; a="414391167" X-IronPort-AV: E=Sophos;i="5.99,249,1677571200"; d="scan'208";a="414391167" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 04 May 2023 05:45:43 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10699"; a="871336492" X-IronPort-AV: E=Sophos;i="5.99,249,1677571200"; d="scan'208";a="871336492" Received: from orsmsx602.amr.corp.intel.com ([10.22.229.15]) by orsmga005.jf.intel.com with ESMTP; 04 May 2023 05:45:43 -0700 Received: from orsmsx603.amr.corp.intel.com (10.22.229.16) 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; Thu, 4 May 2023 05:45:43 -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; Thu, 4 May 2023 05:45:43 -0700 Received: from NAM10-BN7-obe.outbound.protection.outlook.com (104.47.70.109) 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; Thu, 4 May 2023 05:45:42 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=cxY/sXVA/5kojbEP9lNJsO6+z8P3Vnx/qfboA9RBqFQx3kOxTLwEJGlBnpurTIXt26KcGPkUnQcViTp+MbPx2Py52xaz3dfR1+gCyQDA0KTDiwxspgV+1wRWJiH538wAPfU1R1JGDRcNskDFLeGvO5z4pIqUXcyhP+GEZ6Nej+e1TnpzkthTluiWdj53BnKUyy4dFX14cTGyjxfDSBM4dhf4iwMLYXsvk6kG165pHgYWA/pg5tLkqU8v1jF1GwpvdCZg+nSDj2Vzbc7WXXFJnNnb7jDkxy2/KMwMXO5j5bojn0K6/VP4zS6JVq+tgZgolxfxArSahi1nHcjrzjMrMQ== 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=L26roTkTum7Ko90WH8QXJuQkMC986U+o0k463p15Jus=; b=WCB8tcNgj3PTmQ/+OrcUVwmBRCrBXDjaAHAjJ64xXrtFBojnHarxqCk1iSufQqGrk5qg7Qn8FZOeZ2UvGY5sbZ3cvfavOiSzp3QFwajSu55OBy5QNWuq1o0pQEXkKswo8Lb93BMHr6VN2Hf/d0BFczPbQSCYtN6KuP//rD/c1EnikSpW9XkM8hfXWe/seZOU99FDtcV7Ejgk1szEPfroxf5XgVBwksVc7ALN0tZC8fBTdtTtRgHv2IeSghUbZ1PqoYMbPJIWNhdXWPooBu7uyu4sUXt28xrYY0F6pLJaaI007Tpn7u9jMCWgUhHxSEJta0vW7uoEaNXteoh91+Dz4Q== 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 SJ2PR11MB8323.namprd11.prod.outlook.com (2603:10b6:a03:53f::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6363.26; Thu, 4 May 2023 12:45:40 +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; Thu, 4 May 2023 12:45:39 +0000 Date: Thu, 4 May 2023 13:45: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: <20230504123749.1417259-4-juraj.linkes@pantheon.tech> X-ClientProxiedBy: LO4P123CA0680.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:351::9) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|SJ2PR11MB8323:EE_ X-MS-Office365-Filtering-Correlation-Id: 20b8352d-7342-4c13-faf8-08db4c9d7707 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: gPmci0hdl/sAxxb6Za/ByVUOQCoJrjAcUHLJXjsqUPhoOL9nXjtxnGZG/Kg4u7SkZHIPn1Y40HIHUYHDaRKQpS9L8L07svE4YxR7scWiD3nvbEVBT3Ii4auCRObHW+xGRQIbMeLBD8Bu7A1Y3jofcKpQMXIrduB3+834WOgeOzjG3SLFXh/0x6hbEqgS4y+f+E7UAINa19IOQDLzzEuORAfNFsW0YEQaCboEj9fA8kwvkj2lKYmG6ZbNL0Vag1QqjLhN6Za5UpfRgVC9w+Tlyg2zy86Pzpk+o3eujutI6tPZt3HyKAN1eMHOjRM7n1vshF4dgzRBLQmQGmaCk/6k4ywu2C3xKwmgtJXwQkI3rLjneSLAtGKRHtJAmM6iCpl203z6WSxZ/ECYCui507fnWfa3mFj4Etf3/CIwhsiPoAVaiUwFUeFe4ZNyF2KknfbjqqB+PEN7vQuH0MUrCFlNK1sj/6bKaUvQ7MlFx4UERPvDJhuGcHrGXFjBgRor6Ege+tx/I4GvUyD8/wST11Rp/jMU8W1X6L2ona1+Gudb2vY= 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)(39860400002)(396003)(346002)(136003)(366004)(376002)(451199021)(44832011)(478600001)(966005)(38100700002)(82960400001)(8676002)(5660300002)(8936002)(26005)(6916009)(6666004)(86362001)(66476007)(66946007)(66556008)(4326008)(6486002)(6512007)(83380400001)(6506007)(316002)(186003)(2906002)(41300700001); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?dDFIWkM5TzNiZXNEV05HUm9BRnNabCtVeEl0V1VHajlUZVhyU0ZQckJOT0NY?= =?utf-8?B?ZktJSVpiMjF6VnRTY0d0QXlNTVRNZzU2dW96dXJNcENVcFNLU205QldVZG0r?= =?utf-8?B?ejhkY0tsdGJKaU9ZcDZDT0hnK0ZuSDVUMUVRY0lZTHI3aEhzQitwanNOdzhk?= =?utf-8?B?S2tWN042Y2REUUl2SmpUUm5KTTNMRFpLNFFsVHlIYWJTT05namZtekl4a1lw?= =?utf-8?B?NEwxc3h3OWtJcW1VaitxT205NkZlWTJDY28wczZQcGFwVGFYSTl0eWN1WFRE?= =?utf-8?B?WU9tVWdNa0J1TUhOR0F2NFRMd2F2MkxlNTQ5c09MMXNkdkhWa2RtZmZVaUt1?= =?utf-8?B?NEFidXI4UTZUelhkaWpYL3RqdVpVK1ZOdmliWTErazZLUnFuVHBCSFZHMVdV?= =?utf-8?B?WnUwdHNTRy9la2s5ZW9aVmNsdFdKWURha2ZrS2JPcWRtWjY4cHd2SjdLMmp0?= =?utf-8?B?QW1CNnJpUmI5UWJENlZGaiswaHNMVVZKcjBJNE9lZEJRSk5EQ2NZY05hZmp0?= =?utf-8?B?NHRibmRYU1pzdnU0RW9BWGFhWmNxc2NwTDg4aDBraU9yTFJoV0hia28rZ1Fm?= =?utf-8?B?L2xzaXJBQTJrSXlQY25UM2lKYWdoUUdNM2cwRGxERTFUTlVRd0dmaloyUkRH?= =?utf-8?B?alMvMkpaM0lmUzBkWk04QTNqb1N6Y1QrNGN6akQ4N01yWVlCUFJ6Qm55Z0ZQ?= =?utf-8?B?SFRLYklUaGU5aTZoRDRsTFpjaEJqR3FxSHdpRVBZTDZDbkxxa0R6bHVjTUl3?= =?utf-8?B?VE54L0k5Q0J2TXpQVjJ3dVJISUZ4STNJei9HQ3NUc2QrZFlrd0ZkWWdWQmVB?= =?utf-8?B?Tkh6WngrUS96czFwOUhZZTh6WVhFbGZ0alpvTTVVN29BaE90SmJiZ1FnOFdi?= =?utf-8?B?QkxFdjN0ajRTVHNyZHZEMTlJT2NNb1lIaTFQRmYvZGU1dVJlWlpVYkN0LzEx?= =?utf-8?B?dkdRZkdSRXFNY1hucmJtYnVKVjIxdHJDdkduYmZuTDdOUWVLYnhhdXduTENK?= =?utf-8?B?TkdnUEFueitqdUxKeTdEWlBBRFNIajNTd25YdWlTOU9BMW9kS1JmMnBtR2RQ?= =?utf-8?B?ZUM0QTFjODFteXBnSnRMMEcvR0EyV09JZ2dOOXNycERWTnVBbkcvd0ExaHBY?= =?utf-8?B?amlYZ29wK3NZVEcwN3NKRFNjN1FpR1JqV2xxY2JPNjNtQVNRNGZ1RDlNN25x?= =?utf-8?B?aUl2ZE42V29jL3RTSVJyTmZIL0NNOS9aN3VEVmtlcUlvVFVQaDZsOUJvZlpw?= =?utf-8?B?cGNOdWYvNzdHRFhLYnRLL3V5N3hqZ1paV0pjeFkwZGFEdHlzSmx2aldtR3Zr?= =?utf-8?B?bnhoRm5wYzJBYVd2K1l0cnhhTkM0SFBzaTByRzJ4Wnoxd3ppNExmem1sNjJJ?= =?utf-8?B?eDVZY1dqbUFSaVR3Q3FvT2kvd3hvVXIzNWV3cm8rcGFsb1phR0tLSk1hQkdh?= =?utf-8?B?MFYzSEswcEQ5WGFSSmxDRGx3T3BML29zdGFBK1RtVnUwdVg5Z1dPYzV2QlA1?= =?utf-8?B?OGpKelRWeStlSWZnbkRTdkRoM2QybzR0NnBPdUE5emVXY3o1OFhwbVBHNE8y?= =?utf-8?B?cFc0ZGJhdE5mdlBRTTZqNXVRNC9NdVY1aG9lSVhlanNDOW1qQ2llWDRtNm1r?= =?utf-8?B?RVBZaTV0UzFnZE9RTlBRdy9HeTFvQU52UjlwdThoREdCdUV1NzBDeGR5ai96?= =?utf-8?B?QTF3SndIQkRsMjY5eGx4WkZJZzlPYUYzOXd5VlExanRHclJRbGVISU8xMnMx?= =?utf-8?B?RmVoM1ZGWnZQUnFGRlo5alVYYnRoQVd0VFZFbWU2ZVN6VkZFMy9hai96UzQv?= =?utf-8?B?eTRnVTNLdUZwVW9xOHRadE1KRmhoUGNudjlPUk1hVndEOVB6TXhTUjIvRC9N?= =?utf-8?B?d29aMzJvZ0poK3BWLzhZWk51M1JIZEd4V29hc3M1bE5yVyttUUN0YzFEb1hk?= =?utf-8?B?UUZBV3owa0tBem43Q2YrNTV4aEh1cEEreEU1UVZhenBnNHVPR1lMUVpUQ0ZP?= =?utf-8?B?R2lldWVtazVrMGFEd3UwakgydysyL251UUVGTGZFR0s2cjZEVWZ6dzhuKyt1?= =?utf-8?B?b2JjTmc3enV6YkNaUFI3SEZxNG50bDVTVDI4L0JjaUVIUm10ZlRxYXpkUVZp?= =?utf-8?B?WTZINFRWNzBmNFkwbDM1ZXUwUWlCL2xNSWNtZmp4emM3Y2s5M1Jxdk1YeVpP?= =?utf-8?B?OEE9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: 20b8352d-7342-4c13-faf8-08db4c9d7707 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 04 May 2023 12:45:39.5239 (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: k1s3M2WlDFXz8Jh7Cnqz379KXlGlxNDeO9s/0b6vMTauLuvp0AVwisdFP6KdVlbK/lpq3F+o8TB5dguFyYZJPki7kSpVJOVvgHSj73ehGKQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ2PR11MB8323 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', > + 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"