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>

1 files changed, 233 insertions, 0 deletions

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($) {