kernel-doc: produce RestructuredText output

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@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 29fd5ca..0ad1fb0 100755 (executable)
--- 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($) {