From 318824bc9f4615ef9320e436604da63e33f900d4 Mon Sep 17 00:00:00 2001 From: Mitch Jackson Date: Fri, 1 Feb 2019 01:49:33 -0500 Subject: [PATCH] RT# 81961 Include HTML for POD documentation --- Makefile | 10 +++- bin/pod2html.pl | 114 ++++++++++++++++++++++++++++++++++++++++++ debian/control | 2 +- httemplate/elements/menu.html | 1 + 4 files changed, 125 insertions(+), 2 deletions(-) create mode 100755 bin/pod2html.pl diff --git a/Makefile b/Makefile index 440215856..8c5e0b559 100644 --- a/Makefile +++ b/Makefile @@ -49,6 +49,8 @@ FREESIDE_DOCUMENT_ROOT := $(shell [ ${APACHE_VERSION} = '2.4' ] && echo '/var/ww #apache #FREESIDE_DOCUMENT_ROOT = /usr/local/apache/htdocs/freeside +POD2HTML_DIR = ${FREESIDE_DOCUMENT_ROOT}/docs/library + #deb, redhat, fedora, mandrake, suse, others? INIT_FILE = /etc/init.d/freeside #freebsd @@ -327,7 +329,13 @@ install-chown: chown freeside "${FREESIDE_CACHE}/cache.${DATASOURCE}" chown freeside "${FREESIDE_EXPORT}/export.${DATASOURCE}" -install: install-perl-modules install-docs install-init install-apache install-rt install-torrus install-texmf install-chown +install-pod2html: + echo "${POD2HTML_DIR}" + mkdir -p "${POD2HTML_DIR}" + perl bin/pod2html.pl "${POD2HTML_DIR}" + chown freeside:freeside -R "${POD2HTML_DIR}" + +install: install-perl-modules install-docs install-init install-apache install-rt install-torrus install-texmf install-chown install-pod2html deploy: install ${HTTPD_RESTART} diff --git a/bin/pod2html.pl b/bin/pod2html.pl new file mode 100755 index 000000000..935ff1198 --- /dev/null +++ b/bin/pod2html.pl @@ -0,0 +1,114 @@ +#!/usr/bin/env perl + +=head1 NAME + +pod2html.pl + +=head1 DESCRIPTION + +Generate HTML from POD documentation + +Search directories /usr/local/share/perl and /usr/local/bin + +Output HTML to /var/www/html/freeside-doc + +=cut + +use strict; +use warnings; +use v5.10; + +use Pod::Simple::Search; +use Pod::Simple::HTML; +use Pod::Simple::HTMLBatch; + +# Disable this to only build docs for Freeside modules +# This will cause links to non-freeside packages to be broken, +# but save 30-60secs during build process +my $include_system_perl_modules = 1; + + +my $html_dir = shift @ARGV + or HELP_MESSAGE('Please specify an OUTPUT_DIRECTORY'); + +HELP_MESSAGE("Directory $html_dir: No write access!") + unless -w $html_dir; + + +my $parser = Pod::Simple::HTMLBatch->new; + +# Uncomment to suppress status output to STDIN +# $parser->verbose(0); + +$parser->search_class('Inline::Pod::Simple::Search'); +$parser->html_render_class('Inline::Pod::Simple::HTML'); + +# Customized HTML output +our $html_before_title = q{ + <% include( '/elements/header.html', 'Developer Documentation' ) %> + <& /elements/menubar.html, + 'Freeside Perl Modules' => $fsurl.'docs/library/FS.html', + 'Complete Index' => $fsurl.'docs/library/index.html', + &> + +
+

+}; +our $html_after_title = q{

}; +our $html_footer = q{
<% include ('/elements/footer.html' ) %>}; + +$parser->contents_page_start( + "$html_before_title Freeside Documentation Index $html_after_title" +); +$parser->contents_page_end( $html_footer ); + +my @search_dirs = ( + '/usr/local/share/perl/5.24.1', + '/usr/local/bin', + $include_system_perl_modules ? ( + '/usr/share/perl5', + '/usr/share/perl/5.24', + '/usr/share/perl/5.24.1', + ) : (), +); + +$parser->batch_convert( \@search_dirs, $html_dir ); + +sub HELP_MESSAGE { + my $error = shift; + print " ERROR: $error \n" + if $error; + print " + Tool to generate HTML from Freeside POD documentation + + Usage: pod2html.pl OUTPUT_DIRECTORY + + "; + exit; +} + + + +# Subclass Pod::Simple::Search to render POD from files without +# normal perl extensions like PL and PM +package Inline::Pod::Simple::Search; +use base 'Pod::Simple::Search'; + +sub new { + my $class = shift; + my $self = Pod::Simple::Search->new( @_ ); + $self->laborious(1); + $self; +} +1; + + +# Subclass Pod::Simple::HTML to control HTML output +package Inline::Pod::Simple::HTML; +use base 'Pod::Simple::HTML'; + +sub html_header_before_title { $html_before_title } +sub html_header_after_title { $html_after_title } +sub html_footer { $html_footer } + +1; diff --git a/debian/control b/debian/control index 2d463db88..b1855eaaf 100644 --- a/debian/control +++ b/debian/control @@ -91,7 +91,7 @@ Depends: aspell-en,gnupg,ghostscript,gsfonts,gzip,latex-xcolor, libmap-splat-perl, libdatetime-format-ical-perl, librest-client-perl, libbusiness-onlinepayment-perl, libnet-vitelity-perl (>= 0.05), libnet-sslglue-perl, libexpect-perl, - libunicode-truncate-perl (>= 0.303-1) + libunicode-truncate-perl (>= 0.303-1), libpod-simple-perl Suggests: libbusiness-onlinepayment-perl Description: Libraries for Freeside billing and trouble ticketing Freeside is a web-based billing and trouble ticketing application. diff --git a/httemplate/elements/menu.html b/httemplate/elements/menu.html index 18ab7189b..8aa19529e 100644 --- a/httemplate/elements/menu.html +++ b/httemplate/elements/menu.html @@ -878,6 +878,7 @@ if ( $agentnum ) { if $conf->config('ticket_system') eq 'RT_Internal'; $help_menu{'Networking monitoring documentation'} = [ 'http://torrus.org/userguide.pod.html', 'Torrus User Guide' ] if $conf->config('network_monitoring_system') eq 'Torrus_Internal'; + $help_menu{'Developer documentation'} = [ "${fsurl}docs/library/FS.html", 'Developer documentation' ]; $help_menu{'separator'} = ''; $help_menu{"About Freeside v$FS::VERSION"} = [ "javascript:about_freeside()", '' ]; $help_menu{"About RT v$RT::VERSION"} = [ 'http://www.bestpractical.com/rt', 'Request Tracker Homepage' ] -- 2.11.0