Skip to content

L
linux
Commit c0d1b6ee authored by Jonathan Corbet's avatar Jonathan Corbet
1 Browse files
Options

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: default avatarJonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent fadc0b31
Hide whitespace changes
Inline Side-by-side
Showing with 233 additions and 0 deletions
scripts/kernel-doc
View file @ c0d1b6ee
......@@ -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 = '\\&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
......@@ -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($) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7