rt/devel/tools/rt-static-docs

   1 #!/usr/bin/env perl
   2 # BEGIN BPS TAGGED BLOCK {{{
   3 #
   4 # COPYRIGHT:
   5 #
   6 # This software is Copyright (c) 1996-2016 Best Practical Solutions, LLC
   7 #                                          <sales@bestpractical.com>
   8 #
   9 # (Except where explicitly superseded by other copyright notices)
  10 #
  11 #
  12 # LICENSE:
  13 #
  14 # This work is made available to you under the terms of Version 2 of
  15 # the GNU General Public License. A copy of that license should have
  16 # been provided with this software, but in any event can be snarfed
  17 # from www.gnu.org.
  18 #
  19 # This work is distributed in the hope that it will be useful, but
  20 # WITHOUT ANY WARRANTY; without even the implied warranty of
  21 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22 # General Public License for more details.
  23 #
  24 # You should have received a copy of the GNU General Public License
  25 # along with this program; if not, write to the Free Software
  26 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  27 # 02110-1301 or visit their web page on the internet at
  28 # http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
  29 #
  30 #
  31 # CONTRIBUTION SUBMISSION POLICY:
  32 #
  33 # (The following paragraph is not intended to limit the rights granted
  34 # to you to modify and distribute this software under the terms of
  35 # the GNU General Public License and is only of importance to you if
  36 # you choose to contribute your changes and enhancements to the
  37 # community by submitting them to Best Practical Solutions, LLC.)
  38 #
  39 # By intentionally submitting any modifications, corrections or
  40 # derivatives to this work, or any other work intended for use with
  41 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  42 # you are the copyright holder for those contributions and you grant
  43 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  44 # royalty-free, perpetual, license to use, copy, create derivative
  45 # works based on those contributions, and sublicense and distribute
  46 # those contributions and any derivatives thereof.
  47 #
  48 # END BPS TAGGED BLOCK }}}
  49 use strict;
  50 use warnings;
  51
  52 use Getopt::Long;
  53 use File::Temp;
  54 use File::Spec;
  55 use File::Path qw(make_path rmtree);
  56 use File::Copy qw(copy);
  57 use Encode qw(decode_utf8);
  58 use HTML::Entities qw(encode_entities);
  59 use RT::Pod::HTMLBatch;
  60
  61 my %opts;
  62 GetOptions(
  63     \%opts,
  64     "help|h",
  65     "rt=s",
  66     "to=s",
  67 );
  68
  69 if ( $opts{'help'} ) {
  70     require Pod::Usage;
  71     print Pod::Usage::pod2usage( -verbose => 2 );
  72     exit;
  73 }
  74
  75 die "--to=DIRECTORY is required\n"  unless $opts{to};
  76
  77 $opts{to} = File::Spec->rel2abs($opts{to});
  78
  79 make_path( $opts{to} )              unless -e $opts{to};
  80 die "--to MUST be a directory\n"    unless -d $opts{to};
  81
  82 # Unpack the tarball, if that's what we're given.
  83 my $tmpdir;
  84 if (($opts{rt} || '') =~ /\.tar\.gz$/ and -f $opts{rt}) {
  85     $tmpdir = File::Temp->newdir();
  86
  87     system("tar", "xzpf", $opts{rt}, "-C", $tmpdir);
  88     $opts{rt} = <$tmpdir/rt-*>;
  89 }
  90 chdir $opts{rt} if $opts{rt};
  91
  92 my @dirs = (
  93     qw(
  94         docs
  95         etc
  96         lib
  97         bin
  98         sbin
  99         devel/tools
 100         local/lib
 101         local/sbin
 102         local/bin
 103     ),
 104     glob("local/plugins/*/{lib,sbin,bin}"),
 105     glob("docs/UPGRADING*"),
 106 );
 107
 108 my $converter = RT::Pod::HTMLBatch->new;
 109
 110 sub generate_configure_help {
 111     my $configure = shift;
 112     my $help = `./$configure --help`;
 113     my $dest = "$opts{to}/configure.html";
 114
 115     if ($help and open my $html, ">", $dest) {
 116         print $html join "\n",
 117             "<pre>", encode_entities($help), "</pre>", "\n";
 118         close $html;
 119         $converter->note_for_contents_file(["configure options"], $configure, $dest);
 120     } else {
 121         warn "Can't open $dest: $!";
 122     }
 123 }
 124
 125 # Generate a page for ./configure --help if we can
 126 if (-x "configure.ac" and -d ".git") {
 127     rmtree("autom4te.cache") if -d "autom4te.cache";
 128     generate_configure_help("configure.ac");
 129 }
 130 elsif (-x "configure") {
 131     generate_configure_help("configure");
 132 }
 133 else {
 134     warn "Unable to generate a page for ./configure --help!\n";
 135 }
 136
 137 # Manually "convert" README* and 3.8-era UPGRADING* to HTML and push them into
 138 # the known contents.
 139 for my $file (<README* UPGRADING*>) {
 140     (my $name = $file) =~ s{^.+/}{};
 141     my $dest = "$opts{to}/$name.html";
 142
 143     open my $source, "<", $file
 144         or warn "Can't open $file: $!", next;
 145
 146     my $str = "";
 147     $str .= encode_entities(decode_utf8($_)) while <$source>;
 148     close $source;
 149
 150     $str = "<pre>$str</pre>";
 151     $str =~ s{\bdocs/([a-z_-]+)\.pod\b}{<a href="$1.html">docs/$1.pod</a>}ig;
 152     $str =~ s{\betc/(RT_Config)\.pm\b}{<a href="$1.html">etc/$1.pm</a>}g;
 153     $str =~ s{\betc/(UPRGADING\.mysql)\b}{<a href="$1.html">etc/$1</a>}g;
 154     $str =~ s{\b(https?://(?!rt\.example\.com)[.a-z0-9/_:-]+(?<!\.))}{<a href="$1">$1</a>}ig;
 155     $str =~ s{\b([\w-]+\@(lists\.)?bestpractical.com)\b}{<a href="mailto:$1">$1</a>}g;
 156
 157     open my $html, ">", $dest
 158         or warn "Can't open $dest: $!", next;
 159     print $html $str;
 160     close $html;
 161
 162     $converter->note_for_contents_file([$name], $file, $dest);
 163 }
 164
 165 # Copy images into place
 166 make_path("$opts{to}/images/");
 167 copy($_, "$opts{to}/images/")
 168     for <docs/images/*.{png,jpeg,jpg,gif}>;
 169
 170 # Temporarily set executable bits on upgrading doc to work around
 171 # Pod::Simple::Search limitation/bug:
 172 #    https://rt.cpan.org/Ticket/Display.html?id=80082
 173 sub system_chmod {
 174     system("chmod", @_) == 0
 175         or die "Unable to chmod: $! (exit $?)";
 176 }
 177 system_chmod("+x", $_) for <docs/UPGRADING*>;
 178
 179 # Convert each POD file to HTML
 180 $converter->batch_convert( \@dirs, $opts{to} );
 181
 182 # Remove execution bit from workaround above
 183 system_chmod("-x", $_) for <docs/UPGRADING*>;
 184
 185 # Need to chdir back out, if we are in the tmpdir, to let it clean up
 186 chdir "/" if $tmpdir;
 187
 188 exit 0;
 189
 190 __END__
 191
 192 =head1 NAME
 193
 194 rt-static-docs - generate doc shipped with RT
 195
 196 =head1 SYNOPSIS
 197
 198     rt-static-docs --to /path/to/output [--rt /path/to/rt]
 199
 200 =head1 DESCRIPTION
 201
 202 RT ships with documentation (written in POD) embedded in library files, at the
 203 end of utility scripts, and in standalone files.  This script finds all of that
 204 documentation, collects and converts it into a nice set of HTML files, and tops
 205 it off with a helpful index.
 206
 207 Best Practical uses this to publish documentation under
 208 L<http://bestpractical.com/rt/docs/>.
 209
 210 =head1 OPTIONS
 211
 212 =over
 213
 214 =item --to
 215
 216 Set the destination directory for the output files.
 217
 218 =item --rt
 219
 220 Set the RT base directory to search under.  Defaults to the current working
 221 directory, which is fine if you're running this script as
 222 C<devel/tools/rt-static-docs>.
 223
 224 May also point to a tarball (a file ending in C<.tar.gz>) which will be
 225 unpacked into a temporary directory and used as the RT base directory.
 226
 227 =item --help
 228
 229 Print this help.
 230
 231 =back
 232
 233 =cut