From nobody Mon Apr 6 19:40:36 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF0D2C4332F for ; Thu, 13 Oct 2022 17:29:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229931AbiJMR3x (ORCPT ); Thu, 13 Oct 2022 13:29:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:48212 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229846AbiJMR33 (ORCPT ); Thu, 13 Oct 2022 13:29:29 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 611CDC3541; Thu, 13 Oct 2022 10:29:28 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73:8b7:7001:c8aa:b65f]) by ms.lwn.net (Postfix) with ESMTPA id E49D9845; Thu, 13 Oct 2022 17:29:27 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E49D9845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1665682168; bh=0opHrZqvXrL6VtcOxiAU4dw/b0sguVWD5kn6y9m/afo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=CzbjjyF5THDuiifk7pwCcR2BT3lwHJ1v5ySNvbHfr+iosLF/ruylselyA+DC2cr7k weO48FqSQpscOjHUOaMT0rande9wdUNRhRwmwrfsuyNC61y2XEgDygTxApMMj73Xv3 YTx5SpYKE1hI0hkKu6n31+T8rKqr0JJ0uLHVelp+xg7qFM07Sc3WnKvUHbWf7VK38d KXVvscZ1f3llbQC9dVR6YS+LrcL7+bVd6Xmm9HmocARTEiEIOriAgKhD2GYGrddIJ/ DdcHJCEcCo0eizwMAXzE0CpwT/e7OBGYCcxU5bvrZZ4j4pFXPVhxBPx7wqkEAvFw1K 6PVo4JdcFzIXQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org Subject: [PATCH v3 5/6] docs: improve the HTML formatting of kerneldoc comments Date: Thu, 13 Oct 2022 11:29:17 -0600 Message-Id: <20221013172918.846856-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20221013172918.846856-1-corbet@lwn.net> References: <20221013172918.846856-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Make a few changes to cause functions documented by kerneldoc to stand out better in the rendered documentation. Specifically, change kernel-doc to put the description section into a ".. container::" section, then add a bit of CSS to indent that section relative to the function prototype (or struct or enum definition). Tweak a few other CSS parameters while in the neighborhood to improve the formatting. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx-static/custom.css | 16 +++++++- scripts/kernel-doc | 52 ++++++++++++++++---------- 2 files changed, 47 insertions(+), 21 deletions(-) diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-= static/custom.css index 6b0e554cea0a..9b36f7abd24f 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; } =20 /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } -div.document { margin: 20px 10px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } +/* Tweak document margins and don't force width */ +div.document { + margin: 20px 10px 0 10px;=20 + width: auto; +} + +/* + * Parameters for the display of function prototypes and such included + * from C source files. + */ +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0= f3; } +/* indent lines 2+ of multi-line function prototypes */ +dl.function dt { margin-left: 10em; text-indent: -10em; } +dt.sig-object { font-size: larger; } +div.kernelindent { margin-left: 2em; margin-right: 4em; } diff --git a/scripts/kernel-doc b/scripts/kernel-doc index aea04365bc69..85ea80fb5154 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -866,48 +866,53 @@ sub output_function_rst(%) { print "\n"; } =20 - print "**Parameters**\n\n"; + # + # Put our descriptive text into a container (thus an HTML
) to he= lp + # set the function prototypes apart. + # + print ".. container:: kernelindent\n\n"; $lineprefix =3D " "; + print $lineprefix . "**Parameters**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { my $parameter_name =3D $parameter; $parameter_name =3D~ s/\[.*//; $type =3D $args{'parametertypes'}{$parameter}; =20 if ($type ne "") { - print "``$type``\n"; + print $lineprefix . "``$type``\n"; } else { - print "``$parameter``\n"; + print $lineprefix . "``$parameter``\n"; } =20 print_lineno($parameterdesc_start_lines{$parameter_name}); =20 + $lineprefix =3D " "; if (defined($args{'parameterdescs'}{$parameter_name}) && $args{'parameterdescs'}{$parameter_name} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter_name}); } else { - print " *undescribed*\n"; + print $lineprefix . "*undescribed*\n"; } + $lineprefix =3D " "; print "\n"; } =20 - $lineprefix =3D $oldprefix; output_section_rst(@_); + $lineprefix =3D $oldprefix; } =20 sub output_section_rst(%) { my %args =3D %{$_[0]}; my $section; my $oldprefix =3D $lineprefix; - $lineprefix =3D ""; =20 foreach $section (@{$args{'sectionlist'}}) { - print "**$section**\n\n"; + print $lineprefix . "**$section**\n\n"; print_lineno($section_start_lines{$section}); output_highlight_rst($args{'sections'}{$section}); print "\n"; } print "\n"; - $lineprefix =3D $oldprefix; } =20 sub output_enum_rst(%) { @@ -915,6 +920,7 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix =3D $lineprefix; my $count; + my $outer; =20 if ($sphinx_major < 3) { my $name =3D "enum " . $args{'enum'}; @@ -924,14 +930,17 @@ sub output_enum_rst(%) { print "\n\n.. c:enum:: " . $name . "\n\n"; } print_lineno($declaration_start_line); - $lineprefix =3D " "; + $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); print "\n"; =20 - print "**Constants**\n\n"; - $lineprefix =3D " "; + print ".. container:: kernelindent\n\n"; + $outer =3D $lineprefix . " "; + $lineprefix =3D $outer . " "; + print $outer . "**Constants**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { - print "``$parameter``\n"; + print $outer . "``$parameter``\n"; + if ($args{'parameterdescs'}{$parameter} ne $undescribed) { output_highlight_rst($args{'parameterdescs'}{$parameter}); } else { @@ -939,7 +948,7 @@ sub output_enum_rst(%) { } print "\n"; } - + print "\n"; $lineprefix =3D $oldprefix; output_section_rst(@_); } @@ -982,18 +991,19 @@ sub output_struct_rst(%) { } } print_lineno($declaration_start_line); - $lineprefix =3D " "; + $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); print "\n"; =20 - print "**Definition**\n\n"; - print "::\n\n"; + print ".. container:: kernelindent\n\n"; + print $lineprefix . "**Definition**::\n\n"; my $declaration =3D $args{'definition'}; - $declaration =3D~ s/\t/ /g; - print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration= };\n\n"; + $lineprefix =3D $lineprefix . " "; + $declaration =3D~ s/\t/$lineprefix/g; + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$decl= aration" . $lineprefix . "};\n\n"; =20 - print "**Members**\n\n"; $lineprefix =3D " "; + print $lineprefix . "**Members**\n\n"; foreach $parameter (@{$args{'parameterlist'}}) { ($parameter =3D~ /^#/) && next; =20 @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; $type =3D $args{'parametertypes'}{$parameter}; print_lineno($parameterdesc_start_lines{$parameter_name}); - print "``" . $parameter . "``\n"; + print $lineprefix . "``" . $parameter . "``\n"; + $lineprefix =3D " "; output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + $lineprefix =3D " "; print "\n"; } print "\n"; --=20 2.37.2