docs: improve the HTML formatting of kerneldoc commentsalabaster

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.  Tweak a
few other CSS parameters while in the neighborhood to improve the
formatting.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

2 files changed, 23 insertions, 7 deletions

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index c465251e840a..eada9deb29c7 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -10,3 +10,16 @@ div.body h3 { font-size: 130%; }
 
 /* Tighten up the layout slightly */
 div.body { padding: 0 15px 0 10px; }
+
+/* Don't force the document width */
+div.document { width: auto; max-width: 60em; }
+
+/*
+ * Parameters for the display of function prototypes and such included
+ * from C source files.
+ */
+dl.function { margin-top: 2em; background-color: #ecf0f3; }
+/* indent lines 2+ of multi-line function prototypes */
+dl.function dt { margin-left: 10em; text-indent: -10em; }
+dt.sig-object { font-size: larger; }
+div.kernelfunc { margin-left: 2em; margin-right: 4em; }
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index aea04365bc69..e5a802b92782 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -866,17 +866,22 @@ sub output_function_rst(%) {
 	print "\n";
     }
 
-    print "**Parameters**\n\n";
+    #
+    # Put our descriptive text into a container (thus an HTML <div> to help
+    # set the function prototypes apart.
+    #
+    print ".. container:: kernelfunc\n\n";
     $lineprefix = "  ";
+    print $lineprefix . "**Parameters**\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	$type = $args{'parametertypes'}{$parameter};
 
 	if ($type ne "") {
-	    print "``$type``\n";
+	    print $lineprefix . "``$type``\n";
 	} else {
-	    print "``$parameter``\n";
+	    print $lineprefix . "``$parameter``\n";
 	}
 
         print_lineno($parameterdesc_start_lines{$parameter_name});
@@ -890,24 +895,22 @@ sub output_function_rst(%) {
 	print "\n";
     }
 
-    $lineprefix = $oldprefix;
     output_section_rst(@_);
+    $lineprefix = $oldprefix;
 }
 
 sub output_section_rst(%) {
     my %args = %{$_[0]};
     my $section;
     my $oldprefix = $lineprefix;
-    $lineprefix = "";
 
     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 = $oldprefix;
 }
 
 sub output_enum_rst(%) {