Re: [PATCH] doc: flat-table directive

[Mauro Carvalho Chehab]

Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:

> Am 01.07.2016 um 15:09 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
> 
> > On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:  
> >> In Sphinx, the code-block directive is a literal block, no refs or markup
> >> will be interpreted. This is different to what you know from DocBook.
> >> I will look for a solution, that matches your requirement.  
> > 
> > Parsed literal block solves the problem, but brings other problems like
> > requiring escaping for a lot of stuff. And you lose syntax
> > highlighting. It would be great to have a middle ground, like a
> > "semi-parsed code block" where the references are parsed but nothing
> > else.
> > 
> > http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block  

OK, using parsed literal indeed seems to be a solution. The script below
should be doing what's needed to auto-generate the *.h.rst files.
It should be replicating the logic that is done at the media Makefile,
on a cleaner way. It also allows ignoring some symbols. We do that when
we deprecate APIs: they're kept at the header files, but their
descriptions are removed/replaced at the media book.

This is not yet the final version. I need to do some adjustments, as
only the ioctl refs match the ones on media, but it shouldn't be hard to
fix.


Thanks,
Mauro



#!/usr/bin/perl
use strict;

# change to 1 to generate some debug prints
my $debug = 1;

if (scalar @ARGV < 2 || scalar @ARGV > 3) {
	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
}

my ($file_in, $file_out, $file_exceptions) = @ARGV;

my $data;
my @ioctls;
my @defines;
my @typedefs;
my @enums;
my @enum_symbols;
my @structs;

#
# read the file and get identifiers
#

my $is_enum = 0;
open IN, $file_in or die "Can't open $file_in";
while (<IN>) {
	$data .= $_;

	if ($is_enum && m/^\s*([^\s\}]+)\s*[\,=]?/) {
		my $s = $1;
		push @enum_symbols, $1;

		$is_enum = 0 if ($is_enum && m/\}/);

		next;
	}
	$is_enum = 0 if ($is_enum && m/\}/);

	if (m/^\s*#\s*define\s+([A-Z]\S+)\s+_IO/) {
		push @ioctls, $1;
		next;
	}

	if (m/^\s*#\s*define\s+([A-Z]\S+)\s+/) {
		push @defines, $1;
		next
	}

	if (m/^\s*typedef\s+.*\s+(\w\S+);/) {
		push @typedefs, $1;
		next;
	}
	if (m/^\s*enum\s+(\S+)\s+\{/ || m/^\s*enum\s+(\S+)$/) {
		my $v = $1;
		push @enums, $v unless grep{$_ eq $v} @enums;
		$is_enum = $1;
		next;
	}
	if (m/^\s*struct\s+(\S+)\s+\{/ || m/^\s*struct\s+(\S+)$/) {
		my $v = $1;
		push @structs, $v unless grep{$_ eq $v} @structs;
		next;
	}
}
close IN;

#
# Handle multi-line typedefs
#

my @matches = $data =~ m/typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*(\S+)\s*\;/g;
foreach my $m (@matches) {
	push @typedefs, $m unless grep{$_ eq $m} @typedefs;
	next;
}

#
# Handle exceptions, if any
#

if ($file_exceptions) {
	open IN, $file_exceptions or die "Can't read $file_exceptions";
	while (<IN>) {
		next if (m/^\s*$/ || m/^\s*#/);
		if (m/^ignore\s+ioctl\s+(\S+)/) {
			@ioctls = grep { $_ != $1 } @ioctls;
			next;
		}
		if (m/^ignore\s+define\s+(\S+)/) {
			@defines = grep { $_ != $1 } @defines;
			next;
		}
		if (m/^ignore\s+typedef\s+(\S+)/) {
			@typedefs = grep { $_ != $1 } @typedefs;
			next;
		}
		if (m/^ignore\s+enum\s+(\S+)/) {
			@enums = grep { $_ != $1 } @enums;
			next;
		}
		if (m/^ignore\s+struct\s+(\S+)/) {
			@structs = grep { $_ != $1 } @structs;
			next;
		}
		die "Can't parse $file_exceptions";
	}
}

print "ioctls: @ioctls\n" if ($debug && @ioctls);
print "defines: @defines\n" if ($debug && @defines);
print "typedefs: @typedefs\n" if ($debug && @typedefs);
print "enums: @enums\n" if ($debug && @enums);
print "structs: @structs\n" if ($debug && @structs);

#
# Add escape codes for special characters
#
$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;

#
# Align block
#
$data = "    " . $data;
$data =~ s/\n/\n    /g;
$data =~ s/\n\s+$/\n/g;

#
# Add references
#

foreach my $r (@ioctls, @defines, @enum_symbols) {
	my $n = $r;
	$n =~ tr/A-Z/a-z/;
	my $s = ":ref:`$r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/([\s])($r)([\s])/$1$s$3/g;
}

foreach my $r (@enums) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`enum $r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/enum\s+($r)([\s])/$s$2/g;
}

foreach my $r (@structs) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`struct $r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/struct\s+($r)([\s])/$s$2/g;
}

## FIXME

foreach my $r (@typedefs) {
	my $n = $r;
	$n =~ tr/A-Z_/a-z-/;
	my $s = ":ref:`$r <$n>`";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/(typedef\s+^\n+\s+)($r)(\s*;)/$1$s$3/g;
	$data =~ s/(typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*)($r)(\s*;)/$1$s$3/g;
}

#
# Generate output file
#

my $title = $file_in;
$title =~ s,.*/,,;

open OUT, "> $file_out" or die "Can't open $file_out";
print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
print OUT "$title\n";
print OUT "=" x length($title);
print OUT "\n\n.. parsed-literal::\n\n";
print OUT $data;
close OUT;