From nobody Sat Oct 4 16:15:02 2025 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 62D172FCC0B; Fri, 15 Aug 2025 11:51:06 +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=1755258666; cv=none; b=GKAFPpUaLKIWir78JfRMYVHzVycFLGVXgcI+SQ9RMEBWLXYEkGt7uoMmwxB6fntVerftuUFVozQ+unpAw5RcSLegz18H9DBK4TPCHcXDrTuTVUpC8nXzktjQ4KsruKAm+tTVkLH6dvKz+Yn9OsY5j+PGOEdrJQXyDtbNu9qmkHE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1755258666; c=relaxed/simple; bh=ZoOtF8id0ICXUTMlmq1Pqq/MM5WeKdvyH7/glTLcTBs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=AnJX8yFIWKLMCXUbj/4P207wlk8gvQnwBLBTKRO5CzSSdUdaMMTzNW79fGfCTpyxl1e1NJZyz5UPH25lC1S+qohpJtoJs4P4KsbIGYGUDBZlqildo2QSahBk1ksoJxEWjwtChxD23+wIqJqfUfJlQkij+xmr4EKXho18D71iTMc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=oJqbPr+o; 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="oJqbPr+o" Received: by smtp.kernel.org (Postfix) with ESMTPSA id E5371C4CEFC; Fri, 15 Aug 2025 11:51:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1755258665; bh=ZoOtF8id0ICXUTMlmq1Pqq/MM5WeKdvyH7/glTLcTBs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oJqbPr+okVXndDrRx0wc0NynxAK9Hf7ZjlKzaD06dTFia2tJP1ubqqMKadBBiKRfP 6rfoH36bWO1DDRyyn1fiBpcJunXb1MwxA3cV6mBIRxatgkI/rxbzUJ1Dpjpx7u9Iiy Z/qR+2vcKy45Fy/FCV1qJClvrKfvUyfL1XT/RcK4Rlw2BOjsGxqVXt1mr1fp0ouoo+ cyyz06PZ7KjxqF76LJgYR0Mq/8ocBsNefCEgzwD9En2N7m/eMpqpW3pFV1GRyx2CMJ pTJQft2rsqLjh+YZWEKpYkavxgUMdlIULRSdp8yk6N6GWMssksYU6uBCBSACBM33jL 616iVHowj+ObA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1umsxc-000000042oi-0m79; Fri, 15 Aug 2025 13:51:04 +0200 From: Mauro Carvalho Chehab To: Jonathan Corbet , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH 08/11] scripts/sphinx-build-wrapper: restore SPHINXOPTS parsing Date: Fri, 15 Aug 2025 13:50:36 +0200 Message-ID: X-Mailer: git-send-email 2.50.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" While rewriting the wrapper, incidentally support for SPHINXOPTS was dropped. Restore it and better handle them. Signed-off-by: Mauro Carvalho Chehab --- Documentation/Makefile | 1 + scripts/sphinx-build-wrapper | 86 +++++++++++++++++++++++++++++------- 2 files changed, 70 insertions(+), 17 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 280728cf78b9..d2e626627ee6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -19,6 +19,7 @@ endif =20 # You can set these variables from the command line. SPHINXBUILD =3D sphinx-build +SPHINXOPTS =3D SPHINXDIRS =3D . DOCS_THEME =3D DOCS_CSS =3D diff --git a/scripts/sphinx-build-wrapper b/scripts/sphinx-build-wrapper index 5c728956b53c..b9d40f4a6573 100755 --- a/scripts/sphinx-build-wrapper +++ b/scripts/sphinx-build-wrapper @@ -148,10 +148,10 @@ class SphinxBuilder: =20 return path =20 - def __init__(self, venv=3DNone, verbose=3DFalse): + def __init__(self, venv=3DNone, verbose=3DFalse, n_jobs=3DNone): """Initialize internal variables""" self.venv =3D venv - self.verbose =3D verbose + self.verbose =3D None =20 # Normal variables passed from Kernel's makefile self.kernelversion =3D os.environ.get("KERNELVERSION", "unknown") @@ -159,6 +159,34 @@ class SphinxBuilder: self.pdflatex =3D os.environ.get("PDFLATEX", "xelatex") self.latexopts =3D os.environ.get("LATEXOPTS", "-interaction=3Dbat= chmode -no-shell-escape") =20 + if not verbose: + verbose =3D bool(os.environ.get("KBUILD_VERBOSE", "") !=3D "") + + # Handle SPHINXOPTS evironment + sphinxopts =3D shlex.split(os.environ.get("SPHINXOPTS", "")) + + # As we handle number of jobs and quiet in separate, we need to pi= ck + # it the same way as sphinx-build would pick, so let's use argparse + # do to the right argument expansion + parser =3D argparse.ArgumentParser() + parser.add_argument('-j', '--jobs', type=3Dint) + parser.add_argument('-q', '--quiet', type=3Dint) + + # Other sphinx-build arguments go as-is, so place them + # at self.sphinxopts + sphinx_args, self.sphinxopts =3D parser.parse_known_args(sphinxopt= s) + if sphinx_args.quiet =3D=3D True: + self.verbose =3D False + + if sphinx_args.jobs: + self.n_jobs =3D sphinx_args.jobs + + # Command line arguments was passed, override SPHINXOPTS + if verbose is not None: + self.verbose =3D verbose + + self.n_jobs =3D n_jobs + # Source tree directory. This needs to be at os.environ, as # Sphinx extensions and media uAPI makefile needs it self.srctree =3D os.environ.get("srctree") @@ -199,7 +227,7 @@ class SphinxBuilder: else: sys.exit(f"Venv {venv} not found.") =20 - def run_sphinx(self, sphinx_build, sphinx_args, *args, **pwargs): + def run_sphinx(self, sphinx_build, build_args, *args, **pwargs): """ Executes sphinx-build using current python3 command and setting -j parameter if possible to run the build in parallel. @@ -207,11 +235,9 @@ class SphinxBuilder: =20 with JobserverExec() as jobserver: if jobserver.claim: - parallelism =3D str(jobserver.claim) + n_jobs =3D str(jobserver.claim) else: - # As Sphinx has parallelism since version 1.7, we don't ne= ed - # any check here. - parallelism =3D "auto" + n_jobs =3D "auto" # Supported since Sphinx 1.7 =20 cmd =3D [] =20 @@ -222,10 +248,19 @@ class SphinxBuilder: =20 cmd.append(sphinx_build) =20 - if parallelism: - cmd.append("-j" + parallelism) + # if present, SPHINXOPTS or command line --jobs overrides defa= ult + if self.n_jobs: + n_jobs =3D str(self.n_jobs) =20 - cmd +=3D sphinx_args + if n_jobs: + cmd +=3D [f"-j{n_jobs}"] + + if not self.verbose: + cmd.append("-q") + + cmd +=3D self.sphinxopts + + cmd +=3D build_args =20 if self.verbose: print(" ".join(cmd)) @@ -447,9 +482,6 @@ class SphinxBuilder: =20 args.extend(["-D", f"latex_elements.papersize=3D{paper}paper"]) =20 - if not self.verbose: - args.append("-q") - if self.config_rust: args.extend(["-t", "rustdoc"]) =20 @@ -582,6 +614,25 @@ class SphinxBuilder: except OSError as e: sys.exit(f"Failed to restart with {new_python_cmd}: {e}") =20 +def jobs_type(value): + """ + Handle valid values for -j. Accepts Sphinx "-jauto", plus a number + equal or bigger than one. + """ + if value is None: + return None + + if value.lower() =3D=3D 'auto': + return value.lower() + + try: + if int(value) >=3D 1: + return value + + raise argparse.ArgumentTypeError(f"Minimum jobs is 1, got {value}") + except ValueError: + raise argparse.ArgumentTypeError(f"Must be 'auto' or positive inte= ger, got {value}") + def main(): """ Main function. The only mandatory argument is the target. If not @@ -607,18 +658,19 @@ def main(): parser.add_argument("-v", "--verbose", action=3D'store_true', help=3D"place build in verbose mode") =20 + parser.add_argument('-j', '--jobs', type=3Djobs_type, + help=3D"Sets number of jobs to use with sphinx-bui= ld") + parser.add_argument("-V", "--venv", nargs=3D'?', const=3Df'{VENV_DEFAU= LT}', default=3DNone, help=3Df'If used, run Sphinx from a venv dir (defa= ult dir: {VENV_DEFAULT})') =20 args =3D parser.parse_args() =20 - if not args.verbose: - args.verbose =3D bool(os.environ.get("KBUILD_VERBOSE", "") !=3D "") - SphinxBuilder.check_python() =20 - builder =3D SphinxBuilder(venv=3Dargs.venv, verbose=3Dargs.verbose) + builder =3D SphinxBuilder(venv=3Dargs.venv, verbose=3Dargs.verbose, + n_jobs=3Dargs.jobs) =20 builder.build(args.target, sphinxdirs=3Dargs.sphinxdirs, conf=3Dargs.c= onf, theme=3Dargs.theme, css=3Dargs.css, paper=3Dargs.paper) --=20 2.50.1