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 D76E9429E9; Tue, 25 Apr 2023 10:44:14 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C2D62410EA; Tue, 25 Apr 2023 10:44:12 +0200 (CEST) Received: from mga06.intel.com (mga06b.intel.com [134.134.136.31]) by mails.dpdk.org (Postfix) with ESMTP id 7EAA8410DD for ; Tue, 25 Apr 2023 10:44:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1682412251; x=1713948251; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=jpDNiVPBrz/jVZxvNCBbsUfg8JsVpYcPjUGGei/7hfg=; b=JIvWKjKIopdTo8i5USRcV1KKitdwGQe9T8uV/lw1gHz5uT3+wTm2pDVt 4YaSNp6BCytlxPrDRG1CADwDOFsXEg5Jo3CTlMee5ocsyiHgxfswyz4mt MCZ44kHc4KRLwldHyJa23v/r7U+ng+Ts3OBvvkzy18Z0d5dh6f5XBrPFS SP/Jst2iu0tZYdSW6pQRrMRDbLEEjnldDaKu27tkTWCU3eXIJ/KbnyZEW tVRiwX/fSHfX8jKbTMjiub0EZnbYlz9O77AuXsyDD9xKRMoRouhRXBhhW GOW7ouEvxC+bjgJAiImh7jXPfXJkc8fs6AaJO0aeQzo4T1mUwf47hZ+ni Q==; X-IronPort-AV: E=McAfee;i="6600,9927,10690"; a="409642416" X-IronPort-AV: E=Sophos;i="5.99,225,1677571200"; d="scan'208";a="409642416" Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 25 Apr 2023 01:44:10 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10690"; a="726021576" X-IronPort-AV: E=Sophos;i="5.99,225,1677571200"; d="scan'208";a="726021576" Received: from fmsmsx603.amr.corp.intel.com ([10.18.126.83]) by orsmga001.jf.intel.com with ESMTP; 25 Apr 2023 01:44:10 -0700 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) 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, 25 Apr 2023 01:44:10 -0700 Received: from fmsmsx611.amr.corp.intel.com (10.18.126.91) 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; Tue, 25 Apr 2023 01:44:09 -0700 Received: from fmsedg601.ED.cps.intel.com (10.1.192.135) 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 via Frontend Transport; Tue, 25 Apr 2023 01:44:09 -0700 Received: from NAM11-BN8-obe.outbound.protection.outlook.com (104.47.58.168) by edgegateway.intel.com (192.55.55.70) 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 01:44:09 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=IyYei+bInbhph6Md7N8QB7J2uSWnTmDVvlSm9gCYv3kWdNVE8JcF1V8itbnzX6sdoiGGDoxFB2QkUno5p1hUt/WoDW3LgSKfwKQbkugCVhl8ES/IGnuFEHvPwprcH74bwFoJbRJfPvEXnopfZhlwvCn6gH4guqcgwZmPcUCm+YpjNjxg00GJYeUO9FWUzeMYhB4XUzi1/Nng4OV7vjrNVWhTiTazJnJyHNmGAVUoQLGAh6s6E7wnWcxBBCyAgU7SwJiTG4Gzo4Wjo3Uk4ESvSIbsIHm0txiLWlK2d0nYw969lmqnZ3o154QNu4emPS6tooPq5HmCQpDLRKinK75jPA== 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=D6knmqeEubpoYipgnzymmLJX4n5VjIJFEpgyc26uOWQ=; b=WLlGVMarFJR5N2fs/rg9uJLHYj+L062WZM9s/i0x4wrnNbyc54nmFyxsZbru3SYAYrIGr3cwY4AvIhMLt/VdfkNOW3I+If6GWFP/AZW9Gyp6clUwJEPEfKF1ejd7699dn0dT/8++osG9IDWx4Z+tDyI+Kvts5xVg3uIV97fD0NlnKmI42iqXoghAqaLDJ7zm4Ico5r7iIxrz1VDbzaoKoXKhdy31wPbpGFEdIZCtpUpUhZWC12a8AQrq6ufN+8U5qbJyR0bD8AD4ki4ebuFr4hqtnjSF4pd1XzLO9lfrTrjTogF7w0QPbees+7H282I24FyVquSsgGaA/Fv56IAC0Q== 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 BY1PR11MB7982.namprd11.prod.outlook.com (2603:10b6:a03:530::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6319.33; Tue, 25 Apr 2023 08:44:07 +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 08:44:07 +0000 Date: Tue, 25 Apr 2023 09:44:01 +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: LO4P265CA0057.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:2af::14) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|BY1PR11MB7982:EE_ X-MS-Office365-Filtering-Correlation-Id: b56de254-f7db-4adb-20dc-08db45693b5c X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: pcR+ziPpEB0x4J2I/XGwJQsJw8vUDCDpkIxwhajbRscQILK4tc6frLnGVHSm57ABvf+S4LYDNuJ3rWVCHo0Gghq0/GcTK2yKAZJ8684H8+izp0uFhttUyJj7uws1QvGz3Q7kBYj9+0BJWka+wZ+bg+XajbdKpO3I6FTBu9ptVqHJfJROEGChDu8DY/vwEgE+8xS8iZBXvQdiNSw+ysSkNVyRyvaCFTSH7bnng8CINByUQ8Zzex2XoAWUZW5B153sFYsgL9euc1prdLfFKy1y5/GN1R5mAmVd5F9a3F0KjZQy2G/ebc31LS81YwWmpZQJnNa2g5hzP1oWM8qn1r1i2jhpDij9GhVHalIaSYkPg65fkge33OWiEfxrvRqEC3kRoBU8Hw1Qo5KO8jNFq7jSG9N+wtoaOQUKCbmsKI2YflmqBFOYmhYcZlZBkFPvkFVR5ZhHiPir+hWa9jTwL3/nOfiPmhgeDC6FE5r2TY7WXKEDH9gfrC45gp6aC12u5e7IA0J0zOYjQN/K7fzxakZE24etR2TQt5baaznmfzrPzBkpMuNAb02EbH+I4tsW+m+be+c4RERZh63GedJNexzw1KI8Xkr506TphkwgDlcb7+4= 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)(376002)(136003)(346002)(396003)(366004)(451199021)(2906002)(6486002)(966005)(6512007)(6506007)(6666004)(186003)(53546011)(66556008)(66476007)(66946007)(8676002)(8936002)(41300700001)(6916009)(4326008)(316002)(26005)(478600001)(44832011)(5660300002)(82960400001)(38100700002)(86362001)(83380400001)(67856001); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?alVpWHBvNmVML1Jaejd6T3VhdU1YQmxBSWxiSjhBcEc1U0gvRHRVMFdDWEJ6?= =?utf-8?B?OE9SanBPMTM5UE82ZGtIU0xwMm1GbWZxNVgwcXlIb0ZmWEdKWWZQVXNDeGhD?= =?utf-8?B?VUtiTDhteVNNU0tTekQ0OFNteGI4bmZIUTc2NGlRaEdKZWJiRi9BT0Y3TUQw?= =?utf-8?B?Q2tDbFRKWmxmTmRMUmpYL2RLcSsrSEZ5azJUWC9wQVphblVRTm1MMDgyaUVC?= =?utf-8?B?ZXcxWVBseE8yS1FWK3gzYTNJUjBYekxRSUNLdW9GRVR1c0I3U2trZG1wVnhx?= =?utf-8?B?UmhqOHpYZmsxdndCbkcrbmc3a1RxNUpPUUVYeENjOXhaZFZtQzVVSGFpTVdu?= =?utf-8?B?Qk0rQzdzdHZFaW11MXQvcmFrbFFuV251Zy9qa1ZnUTNZZklQblYxVFRpYUpB?= =?utf-8?B?dG9XMjNVRk05cVhXa1drRHFGNkpiU09OOER3dWRjeUZ2RnRkNDNncnBRVzBW?= =?utf-8?B?bmQ1dHdWTDVQejErTWY3cHAvVDJUcTcyeVF0N2d1MkgvYnlHRUxvWitYOUdr?= =?utf-8?B?SGdYMkhlTElSRzkxT2JwYU0xb0NIenNsN1NCQy9OYTdlbUlEVTFNODJmWHlJ?= =?utf-8?B?dE9qVm9jVSt1Nkdkb3FyK0Q2cjNMVHIzcVgxQjZOcmdQMGVhZmtLcUVseU1h?= =?utf-8?B?bVEzT3NmTHZMKzZUVGsyVDRHSDVCT3ZTQnBIZXNwNHRVQ2poR0o2RHg1MThM?= =?utf-8?B?eEw4bHZzZDFaQnNETk1XeTZPRE1BL1lVM2pkM2dFOStyK3hEaDJSSTA5Zk9u?= =?utf-8?B?VlBnSzAvYnFuL1ZOS2gvcDBpVmtkeDV2OGhKMGhLOWtkWXpxNlVFMXMyeTdy?= =?utf-8?B?YTVjelUvQ2FVSW5ROElvay9IdHBicFNWb3VWTTBVenduNzJqamZqVUJ4cFZI?= =?utf-8?B?NUo5enpoc2ZIZHhGeTdMQnloeVdlZlVWUmRtb2k5L0R3U213K1RtcVRFdnlB?= =?utf-8?B?K05IZkpRaTZQVTJGQklINkZhcEVNRHdCL2o3ak10TkFFQWFkRGhuSkd0WjQx?= =?utf-8?B?cUZDVXZFZHJCc25iUElzYXVQRkIzY2FLNHova2hGTkJ0dnVkb3haQUljZjVJ?= =?utf-8?B?ckJrVmRFWUZ6eFhJN0Q5RDk0cHc0MmFoTjNkVWdNWDlENjJsN3R2WFRZZGE1?= =?utf-8?B?N3llRk4zdS95NldIaXN4c0U1NTQvdFZ5WGJwdmdxUWlTZEZyaFA5TGQxSTBT?= =?utf-8?B?VWppeFNyQjRzdEN1ZEcralc0R2tzTTQ1K2FWbFMvNXY4N0srdkdIZDFCUEdY?= =?utf-8?B?M0JSMHN3bVF0Q3RzQmVmV0hQcHIraEphVWNIK01jYm9SdzFRc2FxdWxYNFFs?= =?utf-8?B?WXEyMXhhaFRURzNKOFovaE5XR09BVlhwNGFlTUNZMTBSVFRoZlp5S2ZWanQ2?= =?utf-8?B?TlVCTGkyWFloVlhQcHRTUnJjT2NWQmk0SlBuR2Q1R2dBSjRVWnRqWmtGbFNV?= =?utf-8?B?cjNFTlRDUzNBTlNBYThWRkZmRUpsQ1dSNVBUYmRxajBETzRjUGdnVUxuV3NR?= =?utf-8?B?ZVhMajJiY2cwUHg0dVlWQklKajNkRWx2OUJBQTN1QllTWkNRUEpRamNWSTNN?= =?utf-8?B?RzNPUVA1TEIxcFp3ampCbmdEVGlxYllWVkZyRXRMQlI1YTlZREk3d2hEUStZ?= =?utf-8?B?NDhvMTNxUFlmQml0NzF6ZkkvZWkxQ29hYWxLc0tzTFJXS1ZKVWxzalVNVkNF?= =?utf-8?B?YnZ6eUE0NkMzUnlEb3N0eEZmbFA4bWdaTU5JdDhmc1NqWkdqQzNpaTV3RU9u?= =?utf-8?B?dU9udWRORFFySXZYbGhhMFJrVWFjajJiU0JFU0pyL25OWWlaTVVwZTFwQXRs?= =?utf-8?B?djdwd01xQlpxUktEdTQ1Ykx1WDlHKzZkdVArWW16RExOMXZoRVU2Tm1VcDkz?= =?utf-8?B?R2pxRVNDUkhHNk9rNGZGRTNaNjNHRkY0QWpxNTVZR0NGZk91UFV6SnlYTHdn?= =?utf-8?B?WnExMFRxazdBcElPbFhXM3NmNkRvTjNkaVNXN1k3UTM5V2dJd2tRNXptWWc4?= =?utf-8?B?amN1S1I1NUxpblJMZHRndnlKeW1pOUdvb1kyYUlUWTFLRzNtMHJaUzBTQko2?= =?utf-8?B?amh1Rm91aHBTa1dtejlpRWdYZ3J1TUhBcEIxUlY5VUo5YVFzdVlFWkFwTVlR?= =?utf-8?B?MkZZc0VPMVRtaEphOC9CdjZ5Ni92OEVRTTVibUxTSDI0T3NCemY0TWVFZ2Zh?= =?utf-8?B?MUE9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: b56de254-f7db-4adb-20dc-08db45693b5c X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 Apr 2023 08:44:07.5212 (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: 7r5Mz1ojDb3hyxDBi2AUni5xtyCpOpsVbmIC3aK71d7606yl+X26r97XHzovdMLNROuajBih5/2LRxo1DU+EOyhi9Cz4P3lhn8KwiTE+eTg= X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY1PR11MB7982 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: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? 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. If we are separating them out, I think the dts doc target should be "dts_doc" rather than "dts" for clarity. /Bruce