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.
Unified · Split
| @@ -10,5 +10,19 @@ div.body h3 { font-size: 130%; } · 9 unmodified lines | ||
| 10 | 10 | |
| 11 | 11 | /* Tighten up the layout slightly */ |
| 12 | 12 | div.body { padding: 0 15px 0 10px; } |
| 13 | −div.document { margin: 20px 10px 0 10px; } | |
| 14 | 13 | div.sphinxsidebarwrapper { padding: 1em 0.4em; } |
| 14 | +/* Tweak document margins and don't force width */ | |
| 15 | +div.document { | |
| 16 | + margin: 20px 10px 0 10px; | |
| 17 | + width: auto; | |
| 18 | +} | |
| 19 | + | |
| 20 | +/* | |
| 21 | + * Parameters for the display of function prototypes and such included | |
| 22 | + * from C source files. | |
| 23 | + */ | |
| 24 | +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } | |
| 25 | +/* indent lines 2+ of multi-line function prototypes */ | |
| 26 | +dl.function dt { margin-left: 10em; text-indent: -10em; } | |
| 27 | +dt.sig-object { font-size: larger; } | |
| 28 | +div.kernelindent { margin-left: 2em; margin-right: 4em; } | |
| @@ -866,48 +866,53 @@ sub output_function_rst(%) { · 865 unmodified lines | ||
| 866 | 866 | print "\n"; |
| 867 | 867 | } |
| 868 | 868 | |
| 869 | − print "**Parameters**\n\n"; | |
| 869 | + # | |
| 870 | + # Put our descriptive text into a container (thus an HTML <div>) to help | |
| 871 | + # set the function prototypes apart. | |
| 872 | + # | |
| 873 | + print ".. container:: kernelindent\n\n"; | |
| 870 | 874 | $lineprefix = " "; |
| 875 | + print $lineprefix . "**Parameters**\n\n"; | |
| 871 | 876 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 872 | 877 | my $parameter_name = $parameter; |
| 873 | 878 | $parameter_name =~ s/\[.*//; |
| 874 | 879 | $type = $args{'parametertypes'}{$parameter}; |
| 875 | 880 | |
| 876 | 881 | if ($type ne "") { |
| 877 | − print "``$type``\n"; | |
| 882 | + print $lineprefix . "``$type``\n"; | |
| 878 | 883 | } else { |
| 879 | − print "``$parameter``\n"; | |
| 884 | + print $lineprefix . "``$parameter``\n"; | |
| 880 | 885 | } |
| 881 | 886 | |
| 882 | 887 | print_lineno($parameterdesc_start_lines{$parameter_name}); |
| 883 | 888 | |
| 889 | + $lineprefix = " "; | |
| 884 | 890 | if (defined($args{'parameterdescs'}{$parameter_name}) && |
| 885 | 891 | $args{'parameterdescs'}{$parameter_name} ne $undescribed) { |
| 886 | 892 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); |
| 887 | 893 | } else { |
| 888 | − print " *undescribed*\n"; | |
| 894 | + print $lineprefix . "*undescribed*\n"; | |
| 889 | 895 | } |
| 896 | + $lineprefix = " "; | |
| 890 | 897 | print "\n"; |
| 891 | 898 | } |
| 892 | 899 | |
| 893 | − $lineprefix = $oldprefix; | |
| 894 | 900 | output_section_rst(@_); |
| 901 | + $lineprefix = $oldprefix; | |
| 895 | 902 | } |
| 896 | 903 | |
| 897 | 904 | sub output_section_rst(%) { |
| 898 | 905 | my %args = %{$_[0]}; |
| 899 | 906 | my $section; |
| 900 | 907 | my $oldprefix = $lineprefix; |
| 901 | − $lineprefix = ""; | |
| 902 | 908 | |
| 903 | 909 | foreach $section (@{$args{'sectionlist'}}) { |
| 904 | − print "**$section**\n\n"; | |
| 910 | + print $lineprefix . "**$section**\n\n"; | |
| 905 | 911 | print_lineno($section_start_lines{$section}); |
| 906 | 912 | output_highlight_rst($args{'sections'}{$section}); |
| 907 | 913 | print "\n"; |
| 908 | 914 | } |
| 909 | 915 | print "\n"; |
| 910 | − $lineprefix = $oldprefix; | |
| 911 | 916 | } |
| 912 | 917 | |
| 913 | 918 | sub output_enum_rst(%) { |
| @@ -915,6 +920,7 @@ sub output_enum_rst(%) { · 1 unmodified line | ||
| 915 | 920 | my ($parameter); |
| 916 | 921 | my $oldprefix = $lineprefix; |
| 917 | 922 | my $count; |
| 923 | + my $outer; | |
| 918 | 924 | |
| 919 | 925 | if ($sphinx_major < 3) { |
| 920 | 926 | my $name = "enum " . $args{'enum'}; |
| @@ -924,22 +930,25 @@ sub output_enum_rst(%) { · 3 unmodified lines | ||
| 924 | 930 | print "\n\n.. c:enum:: " . $name . "\n\n"; |
| 925 | 931 | } |
| 926 | 932 | print_lineno($declaration_start_line); |
| 927 | − $lineprefix = " "; | |
| 933 | + $lineprefix = " "; | |
| 928 | 934 | output_highlight_rst($args{'purpose'}); |
| 929 | 935 | print "\n"; |
| 930 | 936 | |
| 931 | − print "**Constants**\n\n"; | |
| 932 | − $lineprefix = " "; | |
| 937 | + print ".. container:: kernelindent\n\n"; | |
| 938 | + $outer = $lineprefix . " "; | |
| 939 | + $lineprefix = $outer . " "; | |
| 940 | + print $outer . "**Constants**\n\n"; | |
| 933 | 941 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 934 | − print "``$parameter``\n"; | |
| 942 | + print $outer . "``$parameter``\n"; | |
| 943 | + | |
| 935 | 944 | if ($args{'parameterdescs'}{$parameter} ne $undescribed) { |
| 936 | 945 | output_highlight_rst($args{'parameterdescs'}{$parameter}); |
| 937 | 946 | } else { |
| 938 | − print " *undescribed*\n"; | |
| 947 | + print $lineprefix . "*undescribed*\n"; | |
| 939 | 948 | } |
| 940 | 949 | print "\n"; |
| 941 | 950 | } |
| 942 | − | |
| 951 | + print "\n"; | |
| 943 | 952 | $lineprefix = $oldprefix; |
| 944 | 953 | output_section_rst(@_); |
| 945 | 954 | } |
| @@ -982,18 +991,19 @@ sub output_struct_rst(%) { · 36 unmodified lines | ||
| 982 | 991 | } |
| 983 | 992 | } |
| 984 | 993 | print_lineno($declaration_start_line); |
| 985 | − $lineprefix = " "; | |
| 994 | + $lineprefix = " "; | |
| 986 | 995 | output_highlight_rst($args{'purpose'}); |
| 987 | 996 | print "\n"; |
| 988 | 997 | |
| 989 | − print "**Definition**\n\n"; | |
| 990 | − print "::\n\n"; | |
| 998 | + print ".. container:: kernelindent\n\n"; | |
| 999 | + print $lineprefix . "**Definition**::\n\n"; | |
| 991 | 1000 | my $declaration = $args{'definition'}; |
| 992 | − $declaration =~ s/\t/ /g; | |
| 993 | − print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; | |
| 1001 | + $lineprefix = $lineprefix . " "; | |
| 1002 | + $declaration =~ s/\t/$lineprefix/g; | |
| 1003 | + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n"; | |
| 994 | 1004 | |
| 995 | − print "**Members**\n\n"; | |
| 996 | 1005 | $lineprefix = " "; |
| 1006 | + print $lineprefix . "**Members**\n\n"; | |
| 997 | 1007 | foreach $parameter (@{$args{'parameterlist'}}) { |
| 998 | 1008 | ($parameter =~ /^#/) && next; |
| 999 | 1009 | |
| @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) { · 3 unmodified lines | ||
| 1003 | 1013 | ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; |
| 1004 | 1014 | $type = $args{'parametertypes'}{$parameter}; |
| 1005 | 1015 | print_lineno($parameterdesc_start_lines{$parameter_name}); |
| 1006 | − print "``" . $parameter . "``\n"; | |
| 1016 | + print $lineprefix . "``" . $parameter . "``\n"; | |
| 1017 | + $lineprefix = " "; | |
| 1007 | 1018 | output_highlight_rst($args{'parameterdescs'}{$parameter_name}); |
| 1019 | + $lineprefix = " "; | |
| 1008 | 1020 | print "\n"; |
| 1009 | 1021 | } |
| 1010 | 1022 | print "\n"; |