Skip to content

Commit

Permalink
kernel-doc: produce RestructuredText output
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
Jonathan Corbet committed May 14, 2016
1 parent fadc0b3 commit c0d1b6e
Showing 1 changed file with 233 additions and 0 deletions.
233 changes: 233 additions & 0 deletions scripts/kernel-doc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -203,6 +204,8 @@ my $type_param = '\@(\w+)';
my $type_struct = '\&((struct\s*)*[_\w]+)';
my $type_struct_xml = '\\&amp;((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
Expand Down Expand Up @@ -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"],
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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(%) {
Expand Down Expand Up @@ -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($) {
Expand Down

0 comments on commit c0d1b6e

Please sign in to comment.