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 D2C2E429E9; Tue, 25 Apr 2023 11:43:40 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5D8D740ED6; Tue, 25 Apr 2023 11:43:40 +0200 (CEST) Received: from mga07.intel.com (mga07.intel.com [134.134.136.100]) by mails.dpdk.org (Postfix) with ESMTP id EBB4A40395 for ; Tue, 25 Apr 2023 11:43:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1682415818; x=1713951818; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=u7f9HorBYMT7+dZwYZ7Avkr0QSgsqxlQq5x8/dNf5PM=; b=WYLJmjAMC+aQEQ7Pe6TNS02Muu3oji2PxIj9uOZ6bsHwR8xGaIU8nCL9 FT/eZ4uiQSbK59v6RHeuH6qZXc3yWG5Bbxt3LNi8c89baTPo57PvfCdeO Ih1yyB9aTOqFCqUTnXIFBVTxQ3ACCIuel38DohRGxyDfn7aODuNE2rbI1 kR6iaKh5OUdsjsQfxcY10FIxe4hI5GhmHCRm4pd5NyzhyX1q4UyZ8og4p /MzggFu4qZ6v3pv8LiXRdkP8guiaTh2mQqSIGswJYrdeQ2UFvXnxM1+9D 3QsRDfKqmYpEIZzWXOVE6ygWqUQIDW1IW2xEGSgkYHOkYec626KjRz6Uz Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10690"; a="412003335" X-IronPort-AV: E=Sophos;i="5.99,225,1677571200"; d="scan'208";a="412003335" Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 Apr 2023 02:43:36 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10690"; a="939708562" X-IronPort-AV: E=Sophos;i="5.99,225,1677571200"; d="scan'208";a="939708562" Received: from fmsmsx601.amr.corp.intel.com ([10.18.126.81]) by fmsmga006.fm.intel.com with ESMTP; 25 Apr 2023 02:43:36 -0700 Received: from fmsmsx611.amr.corp.intel.com (10.18.126.91) 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; Tue, 25 Apr 2023 02:43:36 -0700 Received: from fmsmsx601.amr.corp.intel.com (10.18.126.81) 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, 25 Apr 2023 02:43:36 -0700 Received: from fmsedg602.ED.cps.intel.com (10.1.192.136) 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 via Frontend Transport; Tue, 25 Apr 2023 02:43:36 -0700 Received: from NAM12-MW2-obe.outbound.protection.outlook.com (104.47.66.48) 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, 25 Apr 2023 02:43:35 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=i/5SACHHMRAcWhS3FO/rYaE/oqPtd4CsTq8DX9he1fJzt6PvneDMFFxsVOSzbiBpUjQ+ujiWtaShf/7TZLyupIIywVZG9HIyhYtLy/i+jp0EbKuKani+ubMp4lV5voGT4muw35r+PqlvL9uXMv/vh6cBOj0KCcFjjzg0ooDHrTVCGKHtCjLfnVZVT04oT7/+VVZiTVkkJ8xznlLVcWz05v3pNZivm1CIiHbQinks5rOD1CpI3Tq5piQfGskUl5J050Zff+lV2XIQLD/u0s1IcZuAOd6ekZhLUj/rbgo8O9HAjSEFu49nMr055tmDhmY5fM1FPofLjAFrBFbKdxe1Dg== 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=wxHn01ZlkCc5EPaEgxcVf+zjoBLu42FW8KHvPD7YUlQ=; b=IAxsCNue1bJvBNSr7ecHkYu/Mx6dZ3Owh7qEvsR/ZTz3e9ehTD/pkgPyrHmcutYsE02Gw7aQDQE+xGo8NknNYnfpLD8qkASxGlXQT2zIlwYHCuaXX5JGZlaJ9gFDTpN+Yg3DxNHotrhaYeiFvUU/IZ169HWd9q8h9nxqJHLYMAhdjXUkS6QtUrJemLHTkYkvJcTEVCNBDNDTgR1sVBRDuN+4VwH4rA/z8v4RiEp8qpJRzIKY3OdML0eop3MH7a9A5Nd2HRBsvnXOBwqK9xJTUPtwrDBf+OJQ5Rfdpx6ikTJlyTsb+FNwgmXPf84sZrg7EPxZzqSkVr32dJ2bt0NdKg== 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 CH3PR11MB8362.namprd11.prod.outlook.com (2603:10b6:610:175::6) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6319.34; Tue, 25 Apr 2023 09:43:34 +0000 Received: from DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::b8f3:958:d2c5:2232]) by DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::b8f3:958:d2c5:2232%6]) with mapi id 15.20.6319.033; Tue, 25 Apr 2023 09:43:34 +0000 Date: Tue, 25 Apr 2023 10:43:26 +0100 From: Bruce Richardson To: Juraj =?utf-8?Q?Linke=C5=A1?= CC: Subject: Re: [RFC PATCH v1 0/4] dts: add dts api docs Message-ID: References: <20230323104040.484708-1-juraj.linkes@pantheon.tech> Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-ClientProxiedBy: LO2P265CA0339.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:d::15) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|CH3PR11MB8362:EE_ X-MS-Office365-Filtering-Correlation-Id: ca9f56f5-fefb-4207-425f-08db457188c3 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: +vRVccl/DES3Qi2mYQsRna6wszf6jxL2FwHQ91+OxQDcjfLGnA4ZNURb0nxhpmKfsmc+8RFjl9SRPkv/V0+YYZCdmpPJytHecVZUxYZQsVCP3iJ4Nwsla+n19NrcLvA+iZGUhzgKVaaOOpElPuBn9wmbej/5XJK/f3/mqcfam7WpYRv4mLUGjeJ1m2+jMMFMcL/uRgqTDRA2c6UByvMXEg3QhRcoMZGzL7W8THp9OURY0AvOzO5DPpgJRwqP2pQgrGZC7soB5Rw/+sN9OQGcghuoVjEyRs04l9u5pSMSXQeLHHP7DcJPr4eIFt6p8B4zE+eezS47OjebhSjurilW9kp3qldTqwXuiFFvMjyj33Hlxh6V2SGzdosp4FC+yzWrmDI7ljlaI+P4y8ZnjST4fxusyxAhD392yML6z5JWv6uKvC7dEQf9sBINscmd0bLyNK0ZKjXKYnBgkhdER5+prM0EYWwCKfEWXGgxTPg1jePt7rk+NYORWuYbUq5w/5XsEf2Tfpoes8HLdJJn3Rr1EqTKoi8bH78uw78RUgiYbvEBuFqBPpy2vuCWAdp7IYhpwNiCmMXvvHRs4oF4t+14uQ== 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)(346002)(136003)(376002)(39860400002)(366004)(396003)(451199021)(83380400001)(966005)(478600001)(6486002)(6666004)(6512007)(6506007)(26005)(186003)(53546011)(2906002)(5660300002)(44832011)(82960400001)(38100700002)(66946007)(6916009)(66476007)(66556008)(4326008)(41300700001)(86362001)(8676002)(8936002)(316002); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?NGhEY3Jtb3lVSzBuRnhoL2s2RXYwOXhhQUVRell0Q0JYVHVMNG5YRHBtL1Z4?= =?utf-8?B?cmpiMW01V3Nzcy9Ga3JtMlNIM292MSs4NWRpL1dVMWoxVjc4QVcwQXZoU282?= =?utf-8?B?bm5CL2hQRk5sRXpuRTdHWjI1VDFCMkZYbjZnaVNuci90bkI0eDlwTG9Obkl0?= =?utf-8?B?K3BQUGt2SFFiWDBRU25MMTRrZ0NuYUhjbUNtSjNDVWZPS3ZjZ3owVHRFOGE1?= =?utf-8?B?NnArNTRIYUVURXhRQjVUbzQrd3A5aHlMYjVjRVo3ejZRNE00YnlJdCtrZ1Rs?= =?utf-8?B?ZFIramY2MjNobUhqemVGWk9qRXM4cDU4aENxWG9wVG5LTXNmd3I5L0Q1M29j?= =?utf-8?B?NUJCbDdPbWdyNUdydy9ETnBvbjNROCtDVHpOYU0yVEcrRkFmMU5NSHZ1WjlB?= =?utf-8?B?R0RsTEFKWm50STJLK3EyRTVhYkREWFhwRG9vUjUxYUlCaWJ1V0ZMV1gva1pP?= =?utf-8?B?VXlVOTFzQlZDWVlySXpJVWZvSlhyckdUNGNwYnM1ZDVpaDg4ZkZmWlNjYUlW?= =?utf-8?B?bU15UDkvQmxkKzJGWXlnTnRNUUxza2NJUld1czRDbW1UUjlaSEx0QVYvQzYz?= =?utf-8?B?d0FBSStQN3ZKVCtUYy91YUVUQk44SUpjeFVRc3g5Q2xNWjhwTHk0RU4rRHdK?= =?utf-8?B?bjdlMUpsTDc4dDRmNmZ5QlJhNU90MzFUeHNVU1RaNkRuODdjWk00bzZGSFBY?= =?utf-8?B?ZFE4QWd3cUNnL0NCazdkeVFkLzRBUDFna0Fxdjh4L2NGNW1qWktacDdpZENu?= =?utf-8?B?ZjNHVndTelhseFpIOUxXK2FTN09Dbkppa3E0cnFuTkVnTzNBQzh4UlRmYTlq?= =?utf-8?B?V2RzVEwyMzQ0aWlOcGRqZ3lnbitHS0kzUzlBdXBpQ0QxUzl0S3FwcEVoanRy?= =?utf-8?B?bXZ4SStOMHdoSEpVbVFBakRtaGtuRlo3Q1M4dmFuN2NKNENvc1Bpa3ZvR29i?= =?utf-8?B?MW5SMmlSNWxoaEk3eHpBdXpYWGg1REtycTcrV0NGN055S1pkcjJiSExDSlc1?= =?utf-8?B?SXovMDU5dktPZVJuMDNxMStuZm5XbHpzVmxBZkhFYkNzdHJlSkV2eFlYS2Fu?= =?utf-8?B?TjlpRGZpYXZoMFlVajZlbnBEcHVWT25ScWlSSEc0VmFhMjAvcmQ2TTFZbE5L?= =?utf-8?B?NDVpV0FQUWJFWlRuQmduU0dTSVl1T0VnNWNZRVNIUEJuLzhiVmtBSk5NN2dP?= =?utf-8?B?YWwvT3lRQ0Fta1pRRkI0UVpuNTFoRDZDZjQyaGlpK1hTL2VWUWFrYlNpaURi?= =?utf-8?B?azg0bHJCKzN1NWF1RVNKdWFac2ZRdmFDZVZ1OHY2dVR6UHBOb1FWdmZXaWwy?= =?utf-8?B?VkxzMmFVRTJSQ2kxVk13NVZWRGFGdjROVkZtNUJ4NGpXS3krMlZjeGozMkdT?= =?utf-8?B?TUk0N3l5a0RCRkpraTlhdXZMRzdwMzhGM0N4QVdSSVlub2N6UzBCUGprbzBs?= =?utf-8?B?djVpYkgvSGxrK1VlNGdiTzRpZytrU0xLRG9QWHFvcFYzWjZIbXJTSTRTZ203?= =?utf-8?B?dFVRUkpYUmVCaDRYNzlCYlMzbG9xN3U2RkJ4elJrV1grejVHSmZRZmFOTkpI?= =?utf-8?B?RFpjZXpGbnErblRPWnBwWG9wbFFmQ3lQUmszVzd2d1BrQTg3TC9GZkNnSDQz?= =?utf-8?B?THBJWGVxTmRGYzlhN3E5bjhwU3hKZTI5Z1N2VElpbkxybDM0QUVSam9LWVpt?= =?utf-8?B?Z294RjJMcDFLd0YwNUwvOGJudklxRmZhMWFKY2NvWGJFNm1rT0phUEFYeWVP?= =?utf-8?B?bVlnZzdSTHRrSW1kMmNDN2g3ZXR1ZUNPSXpENUROdnU4TTdBaXFQb05VVXQx?= =?utf-8?B?VldIN3d2TUFmbkQvcVhuOG00YTB6M2VIWnI2M09zcFlnNlhreVdYQlE0TEVQ?= =?utf-8?B?c2htd2lPcitsbkUyRklJZDFiVkg5bFFwQWRSSGpZQTdMN2tLM0VlVW9FckY0?= =?utf-8?B?cElRY1NJdkhIQWM2VWg2RFV1YnBpRXh4dG9rSHJDWlNEakZ6M2hDdXpMZVN5?= =?utf-8?B?SElMTDFyaEtHT3dreVp6ZGdhNkdmdlgxOXA5NHVhZXdGU2tkWUg1N2Z6dnpY?= =?utf-8?B?djBLbzAxYXBpdStldkxIQlltWTArWmlaZ2ozRFpvYnA2T1FBOUxuR01waUxC?= =?utf-8?B?YXpnTWdDczROYlpnNU1jOVdMSDdHMUxxV2pYS0h2cDMyNjBhTmltcWRwMnFi?= =?utf-8?B?cHc9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: ca9f56f5-fefb-4207-425f-08db457188c3 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 Apr 2023 09:43:33.9609 (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: i1inAQX+6O+ceSz6tkUjCG298gKnyw4nEdFFpWnM0z+irl0inp3eB4uWigU6p97YvHYPtw79cDrjwOpdVsXJtqeizF4lRaIEsn3zxmYZui8= X-MS-Exchange-Transport-CrossTenantHeadersStamped: CH3PR11MB8362 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, Apr 25, 2023 at 10:57:12AM +0200, Juraj Linkeš wrote: > On Tue, Apr 25, 2023 at 10:44 AM Bruce Richardson > wrote: > > > > On Tue, Apr 25, 2023 at 10:20:36AM +0200, Juraj Linkeš wrote: > > > On Mon, Apr 3, 2023 at 11:42 AM Bruce Richardson > > > wrote: > > > > > > > > On Mon, Apr 03, 2023 at 11:17:06AM +0200, Juraj Linkeš wrote: > > > > > Hi Bruce, Thomas, > > > > > The meson integration is kinda all over the place. I wanted to use the > > > > > existing conf.py Sphinx config file, but I also wanted to keep the docs > > > > > separated (because of extra DTS api docs dependencies), so the various > > > > > pieces are in different places (the config file in one place, meson > > > > > code in dts directory and generated Sphinx docs are in a new directory > > > > > in the api build dir, separate from the rest of the Sphinx html). > > > > > The big thing here is that I didn't figure out how to separate the dts > > > > > api build from the rest of the docs. I don't know how the -Denable_docs > > > > > option is supposed to work. I wanted to use -Denable_dts_docs in the > > > > > same fashion to decouple the builds, but it doesn't seem to work. > > > > > Reading the code I think the original option doesn't actually do > > > > > anything - does it work? How is it supposed to work? > > > > > Thanks, > > > > > Juraj > > > > > > > > The enable_docs option works by selectively enabling the doc build tasks > > > > using the "build_by_default" parameter on them. > > > > See http://git.dpdk.org/dpdk/tree/doc/guides/meson.build#n23 for an > > > > example. The custom_target for sphinx is not a dependency of any other > > > > task, so whether it gets run or not depends entirely on whether the > > > > "build_by_default" and/or "install" options are set. > > > > > > > > As usual, there may be other stuff that needs cleaning up on this, but > > > > that's how it works for now, anyway. [And it does actually work, last I > > > > tested it :-)] > > > > > > I looked into this and as is so frequently the case, we're both right. :-) > > > > > > When running according to docs, that is with: > > > 1. meson setup doc_build > > > 2. ninja -C doc_build doc > > > > > > it doesn't matter what enable_docs is set to, it always builds the docs. > > > > > > > Yes, I'd forgotten that. That was deliberately done so one could always > > request a doc build directly, without having to worry about DPDK config or > > building the rest of DPDK. > > > > > But in the full build it does control whether docs are built, i.e.: > > > > > > 1. meson setup doc_build > > > 2. ninja -C doc_build > > > doesn't build the docs, whereas: > > > > > > 1. meson setup doc_build -Denable_docs=true > > > 2. ninja -C doc_build > > > builds the docs. > > > > > > Now the problem in this version is when doing just the doc build > > > (ninja -C doc_build doc) both DPDK and DTS docs are built and I'd like > > > to separate those (because DTS doc build has additional dependencies). > > > I'm thinking the following would be a good solution within the current > > > paradigm: > > > 1. The -Denable_docs=true and -Denable_dts_docs=true options to > > > separate doc builds for the full build. > > > 2. Separate dts doc dir for the doc build ("ninja -C doc_build doc" > > > for DPDK docs and "ninja -C doc_build dts" (or maybe some other dir) > > > for DTS docs). > > > > How important is it to separate out the dts docs from the regular docs? > > It is mostly a matter of dependencies. > > > What are the additional dependencies, and how hard are they to get? If > > possible I'd rather not have an additional build config option added for > > this. > > The same dependencies as for running DTS, which are the proper Python > version (3.10 and newer) with DTS depencies obtained with Poetry > (which is a matter of installing Poetry and running it). As is > standard with Python projects, this is all set up in a virtual > environment, which needs to be activated before running the doc build. > It's documented in more detail in the tools docs: > https://doc.dpdk.org/guides/tools/dts.html#setting-up-dts-environment > > This may be too much of a hassle for DPDK devs to build non-DTS docs, > but I don't know whether DPDK devs actually build docs at all. > Can't really say for sure. I suspect most don't build them on a daily basis, but would often need to build them before submitting patches with a doc change included. What format are the DTS docs in? I agree that as described above the requirements are pretty different than those for the regular DPDK docs. > > > > If we are separating them out, I think the dts doc target should be > > "dts_doc" rather than "dts" for clarity. > > Agreed, but "dts_doc" would be a new top-level dir. I think we could > do dts/doc (a dir inside dts). > That path seems reasonable to me. /Bruce