From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4EFBD1DDC08; Sat, 13 Sep 2025 10:18:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757758711; cv=none; b=rNvCRbi8LvH/mFpUh8LGyxweLBEoAeZUN8u8rACClI/NoDiMbyTV49BHpVs0F3Q7ripLX9JTcNEu2l2LgCgc3Tl9BnaZOHh1SDypJZlI0nCJ2IudvFoGWe0khM6HyvYYYTmi80Ryk3mdmJCi7Z+99Qz4XM7i355jA11yzSaoaFk= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757758711; c=relaxed/simple; bh=xxZ7/bSRZZCSdbWxvvdc7KpqpiEO/14awaySh1hSXPI=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=JAcumy7wQ67C7oqCKINdEx6XgJEeHkxbm8aS0RPNAZU6x0+/J8Ser/gSt7UHPhN9cYICJU+6gNa+SPreMXN780u25AHriSq3Y5o4Du2EgoMFl4NdKjv3CZZ/aEX/js4Rw+grtZJ1UvzBAyXIQ/Ixm9Fg6nKjKATqGENo9j/cQhU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=n6Wv3eaO; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="n6Wv3eaO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 428C7C4CEEB; Sat, 13 Sep 2025 10:18:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1757758710; bh=xxZ7/bSRZZCSdbWxvvdc7KpqpiEO/14awaySh1hSXPI=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=n6Wv3eaOzCX43KDux2KQkXsqUYTIGGSFJYpV2oWGOZ7FETL2Ku/Kvp0rysrIf8eW2 M9t9qiYaC5cyXjoX1UMW/nKFPHcUeTdWWMmMSlihRcLACKGiUe2g10Xs/D+0YGTPYy knTdfiZ63fIgeruPw4k7/TzxLNplrQynMUMsQfwGYRK4Wo0ts5nK6fyQYPyDnO9cO/ VGix15BXijALCYvehFZwsDuzun8MuR9NJHp0z8UCwU3nMHv/ACFt+2AkN/YWtEAvAP TfsGQole+bFu5oJ6oOs0W+KuByBidOSvl6R3vdFsqCY2OrcL42rzVjHE7c0Ye08ZlB hVZqCZp6orMpg== Date: Sat, 13 Sep 2025 12:18:25 +0200 From: Mauro Carvalho Chehab To: Vegard Nossum Cc: Jani Nikula , Jonathan Corbet , Linux Doc Mailing List , =?UTF-8?B?QmrDtnJu?= Roy Baron , Alex Gaynor , Alice Ryhl , Boqun Feng , Gary Guo , Trevor Gross , linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org Subject: Re: [PATCH v4 08/19] tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build Message-ID: <20250913121825.002c8edc@foz.lan> In-Reply-To: <3cc0d2bb-d7f7-4e8d-96d5-35863da244b0@oracle.com> References: <20250910145926.453f5441@foz.lan> <45888ca6c88071c754784495b4ef69460ea67b4f@intel.com> <87zfb1p0r3.fsf@trenco.lwn.net> <87ldmkojo5.fsf@trenco.lwn.net> <20250912100645.15c79351@foz.lan> <1e5ea0314833519fdfda3a75c79fd046d41c086d@intel.com> <3cc0d2bb-d7f7-4e8d-96d5-35863da244b0@oracle.com> X-Mailer: Claws Mail 4.3.1 (GTK 3.24.49; x86_64-redhat-linux-gnu) Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Em Fri, 12 Sep 2025 13:34:17 +0200 Vegard Nossum escreveu: > On 12/09/2025 12:16, Jani Nikula wrote: > >> Here, any time increase is problematic, and SPHINXDIRS play an important > >> hole by allowing them to build only the touched documents. > > This is actually problematic, because the SPHINXDIRS partial builds will > > give you warnings for unresolved references that are just fine if the > > entire documentation gets built. > > I admit I don't have a full overview of all the problems that are being > solved here (in existing and proposed code), but how hard would it be to > convert the whole SPHINXDIRS thing into a Sphinx plugin that runs early > and discards documents outside of what the user wants to build? By > "discards" I mean in some useful way that reduces runtime compared to a > full build while retaining some benefits of a full build (reference > checking)? That's not a bad idea, but I guess it is not too easy to implement - at least inside a Sphinx plugin. The good news is that conf.py has already a logic to ignore patterns that could be tweaked and/or placed on a plugin. The bad news is that existing index.rst files will now reference non-existing docs. No idea how to "process" them to filter out such docs. It is probably doable. See, SPHINXDIRS supports pinpointing any directory, not just Documentation child directories. So, eventually, such plugin would also need to "fake" the main index.rst. Now, the question is, if we pick for instance: SPHINXDIRS="netlink/spec networking" What would be the main title that would be at the main index.rst? I suspect that, for such cases, the title of the index would need to be manually set at the command line interface. Another aspect is that SPHINXDIRS affect latex document lists, which can be problematic. Thanks, Mauro