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 F24B32D63E2; Fri, 12 Sep 2025 08:28:18 +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=1757665700; cv=none; b=dwSJSfZfUPmH5+Z8w/bQZYIE6PGg6YyuI7u/IaNIQnBn+UHSpcqZ4K793YM9+5ROgsJTy1M8783VDq1NxiWM5wqm+YNx4of2LOPM0qHeHPRuw93ynXEfBaYQJwP55RzxUcjaRCvx69vCOgSbM1yDUDNBpGp3MvxOrMFNEKgJjLk= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757665700; c=relaxed/simple; bh=n1EW4vy65nSPoafSwWSgXqad37bTolvO1cf0oGnHTWA=; h=Date:From:To:Cc:Subject:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=kxNbQJF2wDwtSxuWVUAseb7lnVwWHLSOrFbWdCMB/6DqO0U7IeA6GkUTF1dmA3XEufPtSjzRQ8WQr3e6wstBG47pWP8A2cWs7fAG+MsOleaPtzf4MljDSvE+Awelm24UIhYfQwRZiHkEiDAVzn1yOSInzm/stqN3Vx0YNAdB9E8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=heMrIWKO; 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="heMrIWKO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 512A3C4CEF4; Fri, 12 Sep 2025 08:28:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1757665698; bh=n1EW4vy65nSPoafSwWSgXqad37bTolvO1cf0oGnHTWA=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=heMrIWKOSv80U/xz5fRNyHaY47UB3AKqXNR30TWBXKEuwFKKAihGB2Ts+rpO5w5Sv SZolg0L0DOBn9xMMvDTsH+jfmQcn7ju81LlqMHVjQ68zo88sBz+vVDEUGKs4PAy8zs JZiCbWaKIG1G4cCgexplVHiGWJAbcoANp4oiZ8c8XYe5B/N4UbN9+mIWf525PkgVj1 SFfE1WFslqHwslAkooJ8EpdkYgoN+mJKNBTbNJPPvBWUfkEfEB0uAkP+ESJYUfbvaC XBUIjzFQcM639J5X/faL1nA5e27Czb9VArnJycIbjAUbK5FqcwNX9F+ltChMSjTTJx Kqg3QiEnGDVsQ== Date: Fri, 12 Sep 2025 10:28:13 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Jani Nikula , 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: <20250912102813.6ea711ca@foz.lan> In-Reply-To: <87zfb1p0r3.fsf@trenco.lwn.net> References: <20250910145926.453f5441@foz.lan> <45888ca6c88071c754784495b4ef69460ea67b4f@intel.com> <87zfb1p0r3.fsf@trenco.lwn.net> X-Mailer: Claws Mail 4.3.1 (GTK 3.24.49; x86_64-redhat-linux-gnu) Precedence: bulk X-Mailing-List: rust-for-linux@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 Thu, 11 Sep 2025 07:38:56 -0600 Jonathan Corbet escreveu: > Mauro Carvalho Chehab writes: > > > On Thu, Sep 11, 2025 at 01:23:55PM +0300, Jani Nikula wrote: > >> > 1. SPHINXDIRS. It needs a lot of magic to work, both before running > >> > sphinx-build and after (inside conf.py); > >> > >> Makes you wonder if that's the right solution to the original > >> problem. It was added as a kind of hack, and it stuck. > > > > The problem is, IMHO, due to the lack of flexibility of sphinx-build: > > It should have a way on it to do partial documentation builds. > > A couple of times I have looked into using intersphinx, making each book > into an actually separate book. The thing I always run into is that > doing a complete docs build, with working references, would require > building everything twice. This is probably worth another attempt one > of these years... The big advantage of intersphinx is for PDF and LaTeX output, as this is the only way to have cross-references there. It is also good for subsystem-specific books (or "sub-"books) like: - Documentation/admin-guide/media/ - Documentation/driver-api/media/ - Documentation/userspace-api/media/ Right now, we create a single book with all those tree, but I would prefer to build each of them as separate units, as they are for separated audiences, but only if cross-references will be solved in a way that html and pdf docs will point to the other books stored at linuxtv.org. For html, this won't be any different, in practice, from what we have, but for PDF and ePub, this would mean smaller books. Thanks, Mauro