From: Jonathan Corbet <corbet@xxxxxxx>
If given the -rst flag, output will now be in RestructuredText. Various
glitches to be worked out yet.
In the end I decided not to use RST section headings within the kerneldoc
comments. gpu.tmpl already has headings five levels deep; adding more is
not going to bring clarity.
This is really just Jani Nikula's asciidoc change with the serial numbers
filed off. It's a hack job that doubtless needs a lot of cleaning up.
Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
Signed-off-by: Jani Nikula <jani.nikula@xxxxxxxxx>
---
scripts/kernel-doc | 233 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 233 insertions(+)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 29fd5cabb657..0ad1fb0e3031 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -55,6 +55,7 @@ Output format selection (mutually exclusive):
-html5 Output HTML5 format.
-list Output symbol list format. This is for use by docproc.
-man Output troff manual page format. This is the default.
+ -rst Output reStructuredText format.
-text Output plain text format.
Output selection (mutually exclusive):
@@ -203,6 +204,8 @@ my $type_param = '\@(\w+)';
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
my $type_env = '(\$\w+)';
+my $type_enum_full = '\&(enum)\s*([_\w]+)';
+my $type_struct_full = '\&(struct)\s*([_\w]+)';
# Output conversion substitutions.
# One for each output format
@@ -268,6 +271,17 @@ my @highlights_text = (
);
my $blankline_text = "";
+# rst-mode
+my @highlights_rst = (
+ [$type_constant, "``\$1``"],
+ [$type_func, "\\:c\\:func\\:`\$1`"],
+ [$type_struct_full, "\\:ref\\:`\$1 \$2`"],
+ [$type_enum_full, "\\:ref\\:`\$1 \$2`"],
+ [$type_struct, "\\:ref\\:`struct \$1`"],
+ [$type_param, "**\$1**"]
+ );
+my $blankline_rst = "\n";
+
# list mode
my @highlights_list = (
[$type_constant, "\$1"],
@@ -404,6 +418,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
$output_mode = "text";
@highlights = @highlights_text;
$blankline = $blankline_text;
+ } elsif ($cmd eq "-rst") {
+ $output_mode = "rst";
+ @highlights = @highlights_rst;
+ $blankline = $blankline_rst;
} elsif ($cmd eq "-docbook") {
$output_mode = "xml";
@highlights = @highlights_xml;
@@ -1704,6 +1722,209 @@ sub output_blockhead_text(%) {
}
}
+##
+# output in restructured text
+#
+
+#
+# This could use some work; it's used to output the DOC: sections, and
+# starts by putting out the name of the doc section itself, but that tends
+# to duplicate a header already in the template file.
+#
+sub output_blockhead_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter, $section);
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print "**$section**\n\n";
+ output_highlight_rst($args{'sections'}{$section});
+ print "\n";
+ }
+}
+
+sub output_highlight_rst {
+ my $contents = join "\n",@_;
+ my $line;
+
+ # undo the evil effects of xml_escape() earlier
+ $contents = xml_unescape($contents);
+
+ eval $dohighlight;
+ die $@ if $@;
+
+ foreach $line (split "\n", $contents) {
+ if ($line eq "") {
+ print $lineprefix, $blankline;
+ } else {
+ $line =~ s/\\\\\\/\&/g;
+ print $lineprefix, $line;
+ }
+ print "\n";
+ }
+}
+
+sub output_function_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter, $section);
+ my $start;
+
+ print ".. c:function:: ";
+ if ($args{'functiontype'} ne "") {
+ $start = $args{'functiontype'} . " " . $args{'function'} . " (";
+ } else {
+ $start = $args{'function'} . " (";
+ }
+ print $start;
+
+ my $count = 0;
+ foreach my $parameter (@{$args{'parameterlist'}}) {
+ if ($count ne 0) {
+ print ", ";
+ }
+ $count++;
+ $type = $args{'parametertypes'}{$parameter};
+ if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
+ # pointer-to-function
+ print $1 . $parameter . ") (" . $2;
+ } else {
+ print $type . " " . $parameter;
+ }
+ }
+ print ")\n\n " . $args{'purpose'} . "\n\n";
+
+ print ":Parameters:\n\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ #$parameter_name =~ s/\[.*//;
+ $type = $args{'parametertypes'}{$parameter};
+
+ if ($type ne "") {
+ print " ``$type $parameter``\n";
+ } else {
+ print " ``$parameter``\n";
+ }
+ if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
+ my $oldprefix = $lineprefix;
+ $lineprefix = " ";
+ output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ $lineprefix = $oldprefix;
+ } else {
+ print "\n _undescribed_\n";
+ }
+ print "\n";
+ }
+ output_section_rst(@_);
+}
+
+sub output_section_rst(%) {
+ my %args = %{$_[0]};
+ my $section;
+ my $oldprefix = $lineprefix;
+ $lineprefix = " ";
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print ":$section:\n\n";
+ output_highlight_rst($args{'sections'}{$section});
+ print "\n";
+ }
+ print "\n";
+ $lineprefix = $oldprefix;
+}
+
+sub output_enum_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $count;
+
+ my $name = "enum " . $args{'enum'};
+ print ".. _" . $name . ":\n\n";
+ print "**$name**\n\n";
+ print " " . $args{'purpose'} . "\n\n";
+
+ print "..\n\n:Constants:\n\n";
+ my $oldprefix = $lineprefix;
+ $lineprefix = " ";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ print " `$parameter`\n";
+ if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
+ output_highlight_rst($args{'parameterdescs'}{$parameter});
+ } else {
+ print " undescribed\n";
+ }
+ print "\n";
+ }
+ $lineprefix = $oldprefix;
+ output_section_rst(@_);
+}
+
+sub output_typedef_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $count;
+ my $name = "typedef " . $args{'typedef'};
+
+ print "**$name**\n\n";
+ print $args{'purpose'} . "\n\n";
+
+ output_section_rst(@_);
+}
+
+sub output_struct_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $name = $args{'type'} . " " . $args{'struct'};
+
+ print ".. _" . $name . ":\n\n";
+ print "**$name**\n\n";
+ print " " . $args{'purpose'} . "\n\n";
+
+ print ":Definition:\n\n";
+ print " ::\n\n";
+ print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ if ($parameter =~ /^#/) {
+ print " " . "$parameter\n";
+ next;
+ }
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
+ $type = $args{'parametertypes'}{$parameter};
+ if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
+ # pointer-to-function
+ print " $1 $parameter) ($2);\n";
+ } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
+ # bitfield
+ print " $1 $parameter$2;\n";
+ } else {
+ print " " . $type . " " . $parameter . ";\n";
+ }
+ }
+ print " };\n\n";
+
+ print ":Members:\n\n";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ ($parameter =~ /^#/) && next;
+
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+
+ ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
+ $type = $args{'parametertypes'}{$parameter};
+ print " `$type $parameter`" . "\n";
+ my $oldprefix = $lineprefix;
+ $lineprefix = " ";
+ output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ $lineprefix = $oldprefix;
+ print "\n";
+ }
+ print "\n";
+ output_section_rst(@_);
+}
+
+
## list mode output functions
sub output_function_list(%) {
@@ -2405,6 +2626,18 @@ sub xml_escape($) {
return $text;
}
+# xml_unescape: reverse the effects of xml_escape
+sub xml_unescape($) {
+ my $text = shift;
+ if (($output_mode eq "text") || ($output_mode eq "man")) {
+ return $text;
+ }
+ $text =~ s/\\\\\\amp;/\&/g;
+ $text =~ s/\\\\\\lt;/</g;
+ $text =~ s/\\\\\\gt;/>/g;
+ return $text;
+}
+
# convert local escape strings to html
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
sub local_unescape($) {
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
