FS/FS/Misc/Pod2Html.pm

   1 package FS::Misc::Pod2Html;
   2 use strict;
   3 use warnings;
   4 use Carp qw( croak );
   5 use File::Copy;
   6 use Pod::Simple::HTML;
   7 use Pod::Simple::HTMLBatch;
   8 use Pod::Simple::Search;
   9
  10 use base 'Exporter';
  11 our @EXPORT_OK = qw(
  12   fs_pod2html
  13   fs_pod2html_from_src
  14   fs_pod2html_from_dirs
  15   $include_system_perl_modules
  16   $quiet_mode
  17 );
  18
  19 our $include_system_perl_modules = 1;
  20 our $quiet_mode = 0;
  21 our $DEBUG = 0;
  22
  23 =head1 NAME
  24
  25 FS::Misc::Pod2Html
  26
  27 =head1 DESCRIPTION
  28
  29 Generate HTML from POD Documentation
  30
  31 =head1 SYNOPSIS
  32
  33 Usage:
  34
  35   use FS::Misc::Pod2Html 'fs_pod2html';
  36   fs_pod2html( '/output/directory' );
  37
  38 Also:
  39
  40   perl -MFS::Misc::Pod2Html -e "FS::Misc::Pod2Html::fs_pod2html('/tmp/pod2html');"
  41
  42 =cut
  43
  44 our $html_before_title = q{
  45   <% include( '/elements/header.html', 'Developer Documentation' ) %>
  46   <& /elements/menubar.html,
  47     'Freeside Perl Modules' => $fsurl.'docs/library/FS.html',
  48     'Complete Index' => $fsurl.'docs/library/index.html',
  49   &>
  50
  51   <div style="width: 90%; margin: 1em auto; font-size: .9em; border: solid 1px #666; background-color: #eee; padding: 1em;">
  52   <h1 style="margin: .5em; border-bottom: solid 1px #999;">
  53 };
  54
  55 our $html_after_title = q{</h1>};
  56
  57 our $html_footer = q{</div><% include ('/elements/footer.html' ) %>};
  58
  59 =head2 fs_pod2html output_dir
  60
  61 Generates Freeside-themed HTML docuemtnation from installed perl modules
  62
  63 =cut
  64
  65 sub fs_pod2html {
  66   fs_pod2html_from_dirs(
  67     shift,
  68     grep( {-d} glob('/usr/local/share/perl/*')),
  69     '/usr/local/bin',
  70     $include_system_perl_modules ? (
  71       '/usr/share/perl5',
  72       grep {-d} glob('/usr/share/perl/*'),
  73     ) : (),
  74   );
  75 }
  76
  77 =head2 fs_pod2html_from_src output_dir
  78
  79 Generate Freeside-themed HTML documentation from a Freeside source tree
  80
  81 Will fail, unless run with CWD at the root of the Freesidse source tree
  82
  83 =cut
  84
  85 sub fs_pod2html_from_src {
  86   my $html_dir = shift;
  87
  88   fs_pod2html_from_dirs(
  89     $html_dir,
  90     'FS/bin',
  91     'bin',
  92     'FS',
  93     'fs_selfservice/FS-SelfService',
  94     $include_system_perl_modules ? (
  95       '/usr/share/perl5',
  96       grep {-d} glob('/usr/share/perl/*'),
  97     ) : (),
  98   );
  99
 100   # FS-SelfService is loosely packaged:
 101   #   perl modules are not stored in lib/FS, scripts not stored in /bin, so
 102   # batch_convert() places these .html in the wrong locations
 103   #
 104   # Copy to correct locations, and correct relative links
 105   copy( "$html_dir/SelfService.html", "$html_dir/FS/SelfService.html" );
 106   mkdir( "$html_dir/FS/SelfService" );
 107   copy( "$html_dir/SelfService/XMLRPC.html", "$html_dir/FS/SelfService/XMLRPC.html" );
 108     for my $sed_cmd (
 109     'sed -i "s/href=\"\.\//href=\"\.\.\//g" "'.$html_dir.'/FS/SelfService.html"',
 110     'sed -i "s/href=\"\\..\//href=\"\.\.\/\.\.\//g" "'.$html_dir.'/FS/SelfService/XMLRPC.html"',
 111   ) {
 112     `$sed_cmd`
 113   }
 114 }
 115
 116 =head2 fs_pod2html output_dir @source_scan_dirs
 117
 118 Generate Freeside-themed HTML documentation, scanning the provided directories
 119
 120 =cut
 121
 122 sub fs_pod2html_from_dirs {
 123   my $html_dir = shift
 124     or croak 'Please specify an output directory';
 125
 126   croak "Directory $html_dir: No write access"
 127     unless -w $html_dir;
 128
 129   my @search_dirs = @_;
 130
 131   for my $dir ( @search_dirs ) {
 132     unless ( -d $dir ) {
 133       croak "Cannot continue - source directory ($dir) not found! ";
 134     }
 135   }
 136
 137   my $parser = Pod::Simple::HTMLBatch->new;
 138
 139   $parser->verbose(0)
 140     if $quiet_mode;
 141
 142   $parser->verbose(2)
 143     if $DEBUG;
 144
 145   $parser->search_class('Inline::Pod::Simple::Search');
 146   $parser->html_render_class('Inline::Pod::Simple::HTML');
 147   $parser->contents_page_start(
 148     "$html_before_title Freeside Documentation Index $html_after_title"
 149   );
 150   $parser->contents_page_end( $html_footer );
 151
 152   $parser->batch_convert( \@search_dirs, $html_dir );
 153 }
 154
 155 1;
 156
 157 =head1 NAME
 158
 159 Inline::Pod::Simple::Search
 160
 161 =head2 DESCRIPTION
 162
 163 Subclass of Pod::Simple::Search
 164
 165 Enable searching for POD in all files instead of just .pl and .pm
 166
 167 =cut
 168
 169 package Inline::Pod::Simple::Search;
 170 use base 'Pod::Simple::Search';
 171
 172 sub new {
 173   my $class = shift;
 174   my $self = Pod::Simple::Search->new( @_ );
 175   $self->laborious(1);
 176   $self->verbose(2)
 177     if $DEBUG;
 178   $self;
 179 }
 180
 181 1;
 182
 183 =head1 NAME
 184
 185 Inline::Pod::Simple::HTML
 186
 187 =head2 DESCRIPTION
 188
 189 Subclass of Pod::Simple::HTML
 190
 191 Customize parsed HTML output
 192
 193 =cut
 194
 195 # Subclass Pod::Simple::HTML to control HTML output
 196 package Inline::Pod::Simple::HTML;
 197 use base 'Pod::Simple::HTML';
 198
 199 sub html_header_before_title { $html_before_title }
 200 sub html_header_after_title { $html_after_title }
 201 sub html_footer { $html_footer }
 202
 203 1;