From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 E274E348C7C; Sat, 5 Sep 2026 03:54:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788580485; cv=none; b=c8NBK8mXdR1X++nKnBRF+rC4aVGsDSSIVQe7uAZ9sLsc1+sYvU76YKbUrtCBd8f0ZYg2z9TiHhKPgDo1nP3z3uRYyMH+bfQY65BdmQOiCopb2x21iExkMZDGfQeHFkz6WjSEimn/LyjhVBRX9QSRsMtpyo1yARO6TYj1zznxyMI= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788580485; c=relaxed/simple; bh=QzEHEv8xYqf0BBYtRfwmoT+sXS6FhpyXY1bM4vANBOM=; h=Message-ID:Date:MIME-Version:Subject:To:Cc:References:From: In-Reply-To:Content-Type; b=SlN/BEh2ezmL1xptbw/s1zPAIavgcg0Yf7zhz4nknOQ68lYmyHPAuEuwjbQopJN2lJ7t4d5g9cqcbWZymA8YXmrFrP/j88gOdH/TdMBm3R6W0WNpcsUWk+8QKL8jgS+sMje9TVKWgIcueoIHGZY/c55jYmuIEb/NuQ5Mt77z8r8= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=pass smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=OSmjqKUk; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="OSmjqKUk" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: Content-Type:In-Reply-To:From:References:Cc:To:Subject:MIME-Version:Date: Message-ID:Sender:Reply-To:Content-ID:Content-Description; bh=u2+a3WmhmYeXRp/uYpf+0p324kyOb4FAm+bW3eCxpAc=; b=OSmjqKUkhHJQADe5cUs0s8H67e Nnd7wxW1akbcU/tsPK+bl2eA1CEkOJmv+1KFDRNuZUZnTuW/QZnAEwNw0PQbPHMqUh0pPkOsjK50v Dec2Bub2wUmKrPkOMa1tVKTrAgUE9ZPNYxPPt/q2ccGE5e6I51LhmMNWNqo8vJkzxvv/1K/pbEPBU FHUG//Q4RZTeb+frjWqO9GmkawhY1vI1kgUYcFRXLPzpMSAlgCfEU5383PY/9mzlxYan5yDwYP0+U CbbOSRqdvIej30wn8h5ulLZdihouB/mddluAcNPKfrrhOIJXDMZrkfATtRDW+bVchoHLqWRiv3B7T FCTqCdhQ==; Received: from [50.53.43.113] (helo=[192.168.254.34]) by bombadil.infradead.org with esmtpsa (Exim 4.99.1 #2 (Red Hat Linux)) id 1x2hUD-00000003eXj-33pO; Sat, 05 Sep 2026 03:54:37 +0000 Message-ID: <58d769f8-7378-4f8e-9bf1-b33ef5bf8ca3@infradead.org> Date: Fri, 4 Sep 2026 20:54:36 -0700 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH] docs: parse-headers: Fix script name and stale Makefile reference To: Karl Mehltretter , Jonathan Corbet Cc: Shuah Khan , Mauro Carvalho Chehab , Dongliang Mu , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org References: <20260905025821.83968-1-kmehltretter@gmail.com> Content-Language: en-US From: Randy Dunlap In-Reply-To: <20260905025821.83968-1-kmehltretter@gmail.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit On 9/4/26 7:58 PM, Karl Mehltretter wrote: > The script is tools/docs/parse-headers.py, not parse_headers.py, and its > FILE_RULES argument is optional. Commit 8a298579cdfc ("scripts: > sphinx-build-wrapper: get rid of uapi/media Makefile") removed the > Makefile the text points to as an example; the cross-references are now > generated by the kernel-include directive, so point to a file that uses > it. > > Fixes: d69a03a97a2d ("docs: doc-guide: parse-headers.rst update its documentation") > Fixes: 8a298579cdfc ("scripts: sphinx-build-wrapper: get rid of uapi/media Makefile") > Assisted-by: LLM > Signed-off-by: Karl Mehltretter Acked-by: Randy Dunlap I would like to see documentation for kernel-include added to Documentation/doc-guide/kernel-doc.rst or doc-guide/parse-headers.rst. I'm surprised that it's there already. Thanks. > --- > Documentation/doc-guide/parse-headers.rst | 15 ++++++++------- > 1 file changed, 8 insertions(+), 7 deletions(-) > > diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst > index a7bb01ff04eb..eb36c92e9a06 100644 > --- a/Documentation/doc-guide/parse-headers.rst > +++ b/Documentation/doc-guide/parse-headers.rst > @@ -8,26 +8,27 @@ between the code and the documentation. Adding cross-references for > userspace API files has an additional advantage: Sphinx will generate warnings > if a symbol is not found at the documentation. That helps to keep the > uAPI documentation in sync with the Kernel changes. > -The :ref:`parse_headers.py ` provides a way to generate such > -cross-references. It has to be called via Makefile, while building the > -documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example > -about how to use it inside the Kernel tree. > +The :ref:`parse-headers.py ` provides a way to generate such > +cross-references. During the documentation build, the same parser is used by > +the ``kernel-include`` directive with the ``:generate-cross-refs:`` option. > +Please see ``Documentation/userspace-api/media/cec/cec-header.rst`` for an > +example about how to use it inside the Kernel tree. > > .. _parse_headers: > > -tools/docs/parse_headers.py > +tools/docs/parse-headers.py > ^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > NAME > **** > > -parse_headers.py - parse a C file, in order to identify functions, structs, > +parse-headers.py - parse a C file, in order to identify functions, structs, > enums and defines and create cross-references to a Sphinx book. > > USAGE > ***** > > -parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` > +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` [``FILE_RULES``] > > SYNOPSIS > ******** -- ~Randy