Commit c0d1b6ee authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

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

scripts/kernel-doc

+233 −0
Original line number Diff line number Diff line
@@ -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($) {

CRA Git | Maintained and supported by SUSTech CRA and CCSE