upload-pod-docs.pl

   1 #!/usr/local/bin/perl
   2 # Upload all Webmin API docs in TWiki format to doxfer.com
   3
   4 use Pod::Simple::Wiki;
   5
   6 $doxfer_host = "doxfer.com";
   7 $doxfer_dir = "/home/doxfer/public_html/twiki/data/Webmin";
   8 $temp_pod_dir = "/tmp/doxfer-wiki";
   9
  10 if ($0 =~ /^(.*\/)[^\/]+$/) {
  11         chdir($1);
  12         }
  13 chop($pwd = `pwd`);
  14
  15 # Build list of modules
  16 @mods = ( [ "WebminCore", ".",
  17             [ "web-lib-funcs.pl", "web-lib.pl", "ui-lib.pl" ],
  18             "Core Webmin API" ] );
  19 foreach my $mi (glob("*/module.info")) {
  20         my $mod;
  21         ($mod = $mi) =~ s/\/module.info//;
  22         next if (-l $mod);
  23         my $midata = `cat $mi`;
  24         my @modlibs;
  25         if ($midata =~ /library=(.*)/) {
  26                 @modlibs = split(/\s+/, $1);
  27                 }
  28         else {
  29                 @modlibs = ( $mod."-lib.pl" );
  30                 }
  31         my $desc = $midata =~ /desc=(.*)/ ? $1 : $mod;
  32         $desc .= " module";
  33         my @podlibs;
  34         foreach my $f (@modlibs) {
  35                 if (-r "$mod/$f") {
  36                         my $data = `cat $mod/$f`;
  37                         if ($data =~ /=head1/) {
  38                                 push(@podlibs, $f);
  39                                 }
  40                         }
  41                 }
  42         if (@podlibs) {
  43                 push(@mods, [ "Module $mod", $mod, \@podlibs, $desc ]);
  44                 }
  45         }
  46
  47 # For each, run Pod to Wiki conversion
  48 system("rm -rf $temp_pod_dir ; mkdir $temp_pod_dir");
  49 foreach $m (@mods) {
  50         print STDERR "Doing module $m->[0]\n";
  51         my $wikiname = $m->[1] eq "." ? "ApiWebminCore"
  52                                       : "Api".join("", map { ucfirst($_) }
  53                                                 split(/\-/, $m->[1]));
  54         push(@$m, $wikiname);
  55         my $infile = "/tmp/pod2twiki.in";
  56         open(INFILE, ">$infile");
  57         foreach $f (@{$m->[2]}) {
  58                 # Replace un-decorated =item with =item *
  59                 # This is kosher according to the POD docs, but Pod2wiki doesn't
  60                 # seem to like it
  61                 print STDERR "Doing file $f\n";
  62                 open(ORIGFILE, "$m->[1]/$f");
  63                 while(<ORIGFILE>) {
  64                         if (/^=item\s+([^\*].*)/) {
  65                                 print INFILE "=item * $1\n";
  66                                 }
  67                         else {
  68                                 print INFILE $_;
  69                                 }
  70                         }
  71                 close(ORIGFILE);
  72                 }
  73         close(INFILE);
  74
  75         # Do the conversion
  76         my $outfile = "$temp_pod_dir/$wikiname.txt";
  77         open(OUTFILE, ">$outfile");
  78         print OUTFILE "%TOC%\n\n";
  79         if ($m->[1] eq ".") {
  80                 print OUTFILE "---+ Core Webmin API\n\n";
  81                 }
  82         else {
  83                 print OUTFILE "---+ Functions from module $m->[1]\n\n";
  84                 }
  85         open(INFILE, $infile);
  86         my $parser = Pod::Simple::Wiki->new('twiki');
  87         $parser->output_fh(*OUTFILE);
  88         $parser->parse_file(*INFILE);
  89         close(INFILE);
  90         close(OUTFILE);
  91
  92         # Remove errors block
  93         open(OUT, $outfile);
  94         my @lines = <OUT>;
  95         close(OUT);
  96         open(OUT, ">$outfile");
  97         my $verbatim = 0;
  98         foreach my $l (@lines) {
  99                 last if ($l =~ /POD\s+ERRORS/);
 100                 if ($l =~ /<verbatim>/) {
 101                         $verbatim = 1;
 102                         }
 103                 elsif ($l =~ /<\/verbatim>/) {
 104                         $verbatim = 0;
 105                         }
 106                 elsif (!$verbatim) {
 107                         $l = &html_escape($l);
 108                         }
 109                 print OUT $l;
 110                 }
 111         close(OUT);
 112         }
 113
 114 # Create summary page
 115 open(SUMM, ">$temp_pod_dir/TheWebminAPI.txt");
 116 print SUMM "---+ The Webmin API\n\n";
 117 print SUMM <<EOF;
 118 The Webmin API has a set of core functions that are available to all modules,
 119 and functions exported by other modules that yours can optionally use. The APIs
 120 for which documentation is available are linked to below :
 121
 122 EOF
 123 foreach my $m (@mods) {
 124         print SUMM "   * [[$m->[4]][$m->[3]]]\n";
 125         }
 126 close(SUMM);
 127
 128 # Upload to doxfer
 129 print STDERR "Uploading to $doxfer_host\n";
 130 system("scp $temp_pod_dir/*.txt doxfer\@$doxfer_host:/home/doxfer/public_html/twiki/data/Webmin/");
 131 print STDERR "done\n";
 132
 133 sub html_escape
 134 {
 135 my ($tmp) = @_;
 136 $tmp =~ s/&/&amp;/g;
 137 $tmp =~ s/</&lt;/g;
 138 $tmp =~ s/>/&gt;/g;
 139 $tmp =~ s/\"/&quot;/g;
 140 $tmp =~ s/\'/&#39;/g;
 141 $tmp =~ s/=/&#61;/g;
 142 return $tmp;
 143 }
 144
 145