[Rt-commit] rt branch, 4.0/static-docs, updated. rt-4.0.6-323-g702ba5b
Thomas Sibley
trs at bestpractical.com
Wed Sep 5 18:32:46 EDT 2012
The branch, 4.0/static-docs has been updated
via 702ba5bccd0976b3ad03c95475fdf7bbcda58b76 (commit)
via b32ad6b6b813c53487c70018c813d43c0da18a63 (commit)
via 6e87dff02385f480c4ed76e847df110fa8838970 (commit)
via 612aa5af4f390fb7e119866761821fc5e76b5f92 (commit)
via 99fe0b24ece42897423ea681026fbd8c11b5ea9c (commit)
via abf1ea53536fa47eeade95067c191628ca0b2d81 (commit)
via 981758cfa9f46bd0e7c8c40ab1fef7ac3f66be10 (commit)
from e2866cb39bfa3cad873f9ac06c6427b6de817ea6 (commit)
Summary of changes:
devel/tools/rt-static-docs | 105 ++++++++++------
lib/RT/Pod/HTML.pm | 65 ++++++++++
lib/RT/Pod/HTMLBatch.pm | 107 ++++++++++++++++
lib/RT/Pod/Search.pm | 15 +++
lib/RT/Pod/Simple/HTMLBatch.pm | 273 -----------------------------------------
5 files changed, 257 insertions(+), 308 deletions(-)
create mode 100644 lib/RT/Pod/HTML.pm
create mode 100644 lib/RT/Pod/HTMLBatch.pm
create mode 100644 lib/RT/Pod/Search.pm
delete mode 100644 lib/RT/Pod/Simple/HTMLBatch.pm
- Log -----------------------------------------------------------------
commit 981758cfa9f46bd0e7c8c40ab1fef7ac3f66be10
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 13:31:06 2012 -0700
Cleaner POD → HTML generation using more subclasses
Subclassing not just Pod::Simple::HTMLBatch but also Pod::Simple::XHTML
and Pod::Simple::Seach gives us more fine-grain options in overriding
discovery and output. The end result is less copying of the internals
of HTMLBatch, which will be more maintainable.
Our HTMLBatch subclass writes its own table of contents (index.html) for
the generated doc so that we can exercise full control without dealing
with the absurd implementation details of HTMLBatch's contents
generation.
We now look in local/ directories for POD as well, which will help for
plugins.
diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 95947c9..56e5dfe 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -51,12 +51,17 @@ use strict;
use warnings;
use Getopt::Long;
+use File::Path 'make_path';
use File::Basename 'basename';
-use RT::Pod::Simple::HTMLBatch;
+use RT::Pod::HTMLBatch;
my %opts;
-my $print_header = '';
-GetOptions( \%opts, "help|h", 'rt-root=s', 'to=s', 'print_header' );
+GetOptions(
+ \%opts,
+ "help|h",
+ "rt=s",
+ "to=s",
+);
if ( $opts{'help'} ) {
require Pod::Usage;
@@ -64,37 +69,28 @@ if ( $opts{'help'} ) {
exit;
}
-die "--to is not supplied" unless $opts{to};
-unless ( -e $opts{to} ) {
- require File::Path;
- File::Path::make_path( $opts{to} );
-}
-
-if ( $opts{'rt-root'} ) {
- chdir $opts{'rt-root'};
-}
+die "--to=DIRECTORY is required\n" unless $opts{to};
+make_path( $opts{to} ) unless -e $opts{to};
+die "--to MUST be a directory\n" unless -d $opts{to};
-my @dirs = ( 'docs', 'lib', 'bin', 'sbin', 'etc' );
+chdir $opts{rt} if $opts{rt};
-my $batch = RT::Pod::Simple::HTMLBatch->new;
-$batch->css_flurry(0);
-$batch->javascript_flurry(0);
-#$batch->add_css('rt-docs.css');
+my @dirs = qw(
+ docs
+ etc
+ lib
+ bin
+ sbin
+ local/lib
+ local/sbin
+ local/bin
+ local/plugins
+);
-my $contents_page_start =<<START;
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>RT Documentation</title></head>
-<body class='contentspage'>
-<h1>RT Documentation</h1>
-START
+# Convert each POD file to HTML
+RT::Pod::HTMLBatch->batch_convert( \@dirs, $opts{to} );
-$contents_page_start = '' unless $print_header;
-$batch->contents_page_start($contents_page_start);
-$batch->contents_page_end('');
-$batch->batch_convert( join( ':', @dirs ), $opts{to} );
__END__
@@ -104,13 +100,19 @@ rt-static-docs - generate doc shipped with RT
=head1 SYNOPSIS
- rt-static-docs --rt-root /path/to/rt --to /path/to/output
-
- perl -Ilib devel/tools/rt-static-docs --to share/html/Documentation
+ rt-static-docs --to /path/to/output [--rt /path/to/rt]
=head1 DESCRIPTION
-This script is used to generate documents shipped with RT.
+RT ships with documentation (written in POD) embedded in library files, at the
+end of utility scripts, and in standalone files. This script finds all of that
+documentation, collects and converts it into a nice set of HTML files, and tops
+it off with a helpful index.
+
+Best Practical uses this to publish documentation under
+L<http://bestpractical.com/rt/docs/>. You can run it yourself, however, on
+your local RT and browse the documentation specific to your installation
+(extensions included!).
=head1 OPTIONS
@@ -120,10 +122,15 @@ This script is used to generate documents shipped with RT.
Set the destination directory for the output files.
-=item --print_header
+=item --rt
+
+Set the RT base directory to search under. Defaults to the current working
+directory, which is fine if you're running this script as
+C<devel/tools/rt-static-docs>.
+
+=item --help
-Flag to printer HTML page header on the TOC page. This only effects
-the TOC page. It defaults to off.
+Print this help.
=back
diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
new file mode 100644
index 0000000..fa25119
--- /dev/null
+++ b/lib/RT/Pod/HTML.pm
@@ -0,0 +1,27 @@
+use strict;
+use warnings;
+
+package RT::Pod::HTML;
+use base 'Pod::Simple::XHTML';
+
+sub new {
+ my $self = shift->SUPER::new(@_);
+ $self->index(1);
+ return $self;
+}
+
+sub perldoc_url_prefix { "http://metacpan.org/module/" }
+
+sub html_header { '' }
+sub html_footer { '' }
+
+sub start_Verbatim { $_[0]{'scratch'} = "<pre>" }
+sub end_Verbatim { $_[0]{'scratch'} .= "</pre>"; $_[0]->emit; }
+
+sub _end_head {
+ my $self = shift;
+ $self->{scratch} = '<a href="#___top">' . $self->{scratch} . '</a>';
+ return $self->SUPER::_end_head(@_);
+}
+
+1;
diff --git a/lib/RT/Pod/HTMLBatch.pm b/lib/RT/Pod/HTMLBatch.pm
new file mode 100644
index 0000000..0aa27ae
--- /dev/null
+++ b/lib/RT/Pod/HTMLBatch.pm
@@ -0,0 +1,93 @@
+use strict;
+use warnings;
+
+package RT::Pod::HTMLBatch;
+use base 'Pod::Simple::HTMLBatch';
+
+use RT::Pod::Search;
+use RT::Pod::HTML;
+
+sub new {
+ my $self = shift->SUPER::new(@_);
+ $self->verbose(0);
+
+ # Per-page output options
+ $self->css_flurry(0); # No CSS
+ $self->javascript_flurry(0); # No JS
+ $self->no_contents_links(1); # No header/footer "Back to contents" links
+
+ # TOC options
+ $self->index(1); # Write a per-page TOC
+ $self->contents_file("index.html"); # Write a global TOC
+
+ $self->html_render_class('RT::Pod::HTML');
+ $self->search_class('RT::Pod::Search');
+
+ return $self;
+}
+
+sub write_contents_file {
+ my ($self, $to) = @_;
+ return unless $self->contents_file;
+
+ my $file = join "/", $to, $self->contents_file;
+ open my $index, ">", $file
+ or warn "Unable to open index file '$file': $!\n", return;
+
+ my $pages = $self->_contents;
+ return unless @$pages;
+
+ # Classify
+ my %toc;
+ for my $page (@$pages) {
+ my ($name, $infile, $outfile, $pieces) = @$page;
+ my $section = $infile =~ m{/plugins/([^/]+)} ? "05 Extension: $1" :
+ $infile =~ m{/local/} ? '04 Local Documenation' :
+ $infile =~ m{/(docs|etc)/} ? '01 User Documentation' :
+ $infile =~ m{/bin/} ? '02 Utilities (bin)' :
+ $infile =~ m{/sbin/} ? '03 Utilities (sbin)' :
+ $name =~ /^RT::Action/ ? '08 Actions' :
+ $name =~ /^RT::Condition/ ? '09 Conditions' :
+ $name =~ /^RT(::|$)/ ? '07 Developer Documentation' :
+ '06 Miscellaneous' ;
+
+ if ($section =~ /User/) {
+ $name =~ s/_/ /g;
+ $name = join "/", map { ucfirst } split /::/, $name;
+ }
+
+ (my $path = $outfile) =~ s{^\Q$to\E/?}{};
+
+ push @{ $toc{$section} }, {
+ name => $name,
+ path => $path,
+ };
+ }
+
+ # Write out index
+ print $index "<dl class='superindex'>\n";
+
+ for my $key (sort keys %toc) {
+ next unless @{ $toc{$key} };
+
+ (my $section = $key) =~ s/^\d+ //;
+ print $index "<dt>", esc($section), "</dt>\n";
+ print $index "<dd>\n";
+
+ for my $page (sort { $a->{name} cmp $b->{name} } @{ $toc{$key} }) {
+ print $index " <a href='", esc($page->{path}), "'>",
+ esc($page->{name}),
+ "</a><br>\n";
+ }
+ print $index "</dd>\n";
+ }
+ print $index '</dl>';
+
+ close $index;
+}
+
+sub esc {
+ Pod::Simple::HTMLBatch::esc(@_);
+}
+
+1;
diff --git a/lib/RT/Pod/Search.pm b/lib/RT/Pod/Search.pm
new file mode 100644
index 0000000..d6ddd2d
--- /dev/null
+++ b/lib/RT/Pod/Search.pm
@@ -0,0 +1,15 @@
+use strict;
+use warnings;
+
+package RT::Pod::Search;
+use base 'Pod::Simple::Search';
+
+sub new {
+ my $self = shift->SUPER::new(@_);
+ $self->laborious(1) # Find scripts too
+ ->limit_re(qr/(?<!\.in)$/) # Filter out .in files
+ ->inc(0); # Don't look in @INC
+ return $self;
+}
+
+1;
diff --git a/lib/RT/Pod/Simple/HTMLBatch.pm b/lib/RT/Pod/Simple/HTMLBatch.pm
deleted file mode 100644
index f03b38a..0000000
--- a/lib/RT/Pod/Simple/HTMLBatch.pm
+++ /dev/null
@@ -1,273 +0,0 @@
-package RT::Pod::Simple::HTMLBatch;
-use base Pod::Simple::HTMLBatch;
-
-=head2 modnames2paths
-
-Override
-
-Set some different options in the Pod::Simple::Search
-object. Probably would be better if Pod::Simple::HTMLBatch
-just took a prepped object as an optional param.
-
-=cut
-
-sub modnames2paths { # return a hashref mapping modulenames => paths
- my($self, $dirs) = @_;
-
- my $m2p;
- {
- my $search = $self->search_class->new;
- DEBUG and print "Searching via $search\n";
- $search->verbose(1) if DEBUG > 10;
- $search->laborious(1); # Added to find scripts in bin and sbin
- $search->limit_re(qr/(?<!\.in)$/); # Filter out .in files
- $search->progress( $self->progress->copy->goal(0) ) if $self->progress;
- $search->shadows(0); # don't bother noting shadowed files
- $search->inc( $dirs ? 0 : 1 );
- $search->survey( $dirs ? @$dirs : () );
- $m2p = $search->name2path;
- die "What, no name2path?!" unless $m2p;
- }
-
- $self->muse("That's odd... no modules found!") unless keys %$m2p;
- if ( DEBUG > 4 ) {
- print "Modules found (name => path):\n";
- foreach my $m (sort {lc($a) cmp lc($b)} keys %$m2p) {
- print " $m $$m2p{$m}\n";
- }
- print "(total ", scalar(keys %$m2p), ")\n\n";
- } elsif ( DEBUG ) {
- print "Found ", scalar(keys %$m2p), " modules.\n";
- }
- $self->muse( "Found ", scalar(keys %$m2p), " modules." );
-
- # return the Foo::Bar => /whatever/Foo/Bar.pod|pm hashref
- return $m2p;
-}
-
-=head2 _prep_contents_breakdown
-
-Override
-
-Modified to create hash entries for the documentation sections
-we want based on where they came from. These entries can then
-be used to create the TOC page.
-
-=cut
-
-sub _prep_contents_breakdown {
- my($self) = @_;
- my $contents = $self->_contents;
- my %toplevel; # maps lctoplevelbit => [all submodules]
- my %toplevel_form_freq; # ends up being 'foo' => 'Foo'
- # (mapping anycase forms to most freq form)
-
- foreach my $entry (@$contents) {
- my $toplevel;
-
- # First, look for specific sections we want docs for and create entries
- # for them.
-
- if ( $entry->[1] =~ /(\/docs\/|\/etc\/)/ ) {
- $toplevel = "RT User Documentation";
- ++$toplevel_form_freq{'user_docs'}{$toplevel};
- push @{ $toplevel{'user_docs'} }, $entry;
- }
- elsif ( $entry->[1] =~ /\/bin\// ){
- $toplevel = "RT Utilities (bin)";
- ++$toplevel_form_freq{'bin_docs'}{$toplevel};
- push @{ $toplevel{'bin_docs'} }, $entry;
- }
- elsif ( $entry->[1] =~ /\/sbin\// ){
- $toplevel = "RT Utilities (sbin)";
- ++$toplevel_form_freq{'sbin_docs'}{$toplevel};
- push @{ $toplevel{'sbin_docs'} }, $entry;
- }
- elsif ( $entry->[3][1] eq 'Action' ){
- $toplevel = "RT Actions";
- ++$toplevel_form_freq{'action_docs'}{$toplevel};
- push @{ $toplevel{'action_docs'} }, $entry;
- }
- elsif ( $entry->[3][1] eq 'Condition' ){
- $toplevel = "RT Conditions";
- ++$toplevel_form_freq{'condition_docs'}{$toplevel};
- push @{ $toplevel{'condition_docs'} }, $entry;
- }
- elsif ( $entry->[1] =~ /\/lib\// ) {
- $toplevel = "RT Developer Documentation";
- ++$toplevel_form_freq{'dev_docs'}{$toplevel};
- push @{ $toplevel{'dev_docs'} }, $entry;
- }
- else {
- # Catch everything else
- my $toplevel =
- $entry->[0] =~ m/^perl\w*$/ ? 'perl_core_docs'
- # group all the perlwhatever docs together
- : $entry->[3][0] # normal case
- ;
- ++$toplevel_form_freq{ lc $toplevel }{ $toplevel };
- push @{ $toplevel{ lc $toplevel } }, $entry;
- push @$entry, lc($entry->[0]); # add a sort-order key to the end
- }
- }
-
- foreach my $toplevel (keys %toplevel) {
- my $fgroup = $toplevel_form_freq{$toplevel};
- $toplevel_form_freq{$toplevel} =
- (
- sort { $fgroup->{$b} <=> $fgroup->{$a} or $a cmp $b }
- keys %$fgroup
- # This hash is extremely unlikely to have more than 4 members, so this
- # sort isn't so very wasteful
- )[0];
- }
-
- return(\%toplevel, \%toplevel_form_freq) if wantarray;
- return \%toplevel;
-}
-
-=head2 _write_contents_middle
-
-Override
-
-Add more control over the order of sections in the TOC file.
-
-=cut
-
-sub _write_contents_middle {
- my($self, $Contents, $outfile, $toplevel2submodules, $toplevel_form_freq) = @_;
-
- $self->format_toc_link_text($toplevel2submodules->{user_docs});
-
- # Build the sections of the TOC in the order we want
- my @toc_sections = qw(user_docs bin_docs sbin_docs dev_docs action_docs condition_docs);
- foreach my $section ( @toc_sections ){
- $self->_write_content_subsection($Contents, $outfile, $toplevel2submodules,
- $section, $toplevel_form_freq->{$section});
- }
-}
-
-=head2 _write_content_subsection
-
-Override
-
-Remove the outer loop since we are calling each section deliberately in the
-order we want. Still use the main logic to write the content of inner sections.
-
-=cut
-
-sub _write_content_subsection {
- my($self, $Contents, $outfile, $toplevel2submodules, $section, $section_title) = @_;
-
- my @downlines = sort {$a->[0] cmp $b->[0]}
- @{ $toplevel2submodules->{$section} };
-
- printf $Contents qq[<dt><a name="%s">%s</a></dt>\n<dd>\n],
- Pod::Simple::HTML::esc( $section, $section_title )
- ;
-
- my($path, $name);
- foreach my $e (@downlines) {
- $name = $e->[0];
- $path = join( "/", '.', Pod::Simple::HTML::esc( @{$e->[3]} ) )
- . ($HTML_EXTENSION || $Pod::Simple::HTML::HTML_EXTENSION);
- print $Contents qq{ <a href="$path">}, Pod::Simple::HTML::esc($name), "</a> \n";
- }
- print $Contents "</dd>\n\n";
- return 1;
-}
-
-=head2 batch_mode_page_object_init
-
-Override
-
-Change init options for the Pod::Simple::HTML object that writes out the
-pages.
-
-=cut
-
-sub batch_mode_page_object_init {
- my $self = shift;
- my($page, $module, $infile, $outfile, $depth) = @_;
-
- $page->default_title('');
- $page->force_title(''); # Force the title off.
- $page->index( $self->index );
-
- $page->html_header_before_title('');
- $page->html_header_after_title('');
- $page->html_footer('');
- $page->html_css( $self-> _css_wad_to_markup($depth) );
- $page->html_javascript( $self->_javascript_wad_to_markup($depth) );
-
- $self->add_header_backlink($page, $module, $infile, $outfile, $depth);
- $self->add_footer_backlink($page, $module, $infile, $outfile, $depth);
-
- return $self;
-}
-
-=head2 add_header_backlink
-
-Override
-
-Update backlink in header
-
-=cut
-
-sub add_header_backlink {
- my $self = shift;
- return if $self->no_contents_links;
- my($page, $module, $infile, $outfile, $depth) = @_;
- $page->html_header_after_title( join '',
- $page->html_header_after_title || '',
-
- qq[<p class="backlinktop"><b><a name="___top" href="],
- $self->url_up_to_contents($depth),
- qq[" accesskey="1" title="All Documents">Back to Index</a></b></p>\n],
- )
- if $self->contents_file
- ;
- return;
-}
-
-=head2 add_footer_backlink
-
-Override
-
-Update backlink in footer
-
-=cut
-
-sub add_footer_backlink {
- my $self = shift;
- return if $self->no_contents_links;
- my($page, $module, $infile, $outfile, $depth) = @_;
- $page->html_footer( join '',
- qq[<p class="backlinkbottom"><b><a name="___bottom" href="],
- $self->url_up_to_contents($depth),
- qq[" title="All Documents">Back to Index</a></b></p>\n],
-
- $page->html_footer || '',
- )
- if $self->contents_file
- ;
- return;
-}
-
-=head2 format_toc_link_text
-
-Apply some formatting to the visible links for user documentation.
-
-=cut
-
-sub format_toc_link_text {
- my ($self, $content) = @_;
-
- foreach my $entry ( @{$content} ){
- $entry->[0] =~ s/_/ /g;
- $entry->[0] = join '/', map {ucfirst} split /::/, $entry->[0];
- }
-
-}
-
-1;
commit abf1ea53536fa47eeade95067c191628ca0b2d81
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 13:37:45 2012 -0700
Resolve local POD links to the pages we're generating
diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index fa25119..669bd22 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -24,4 +24,38 @@ sub _end_head {
return $self->SUPER::_end_head(@_);
}
+sub resolve_pod_page_link {
+ my $self = shift;
+ my ($name, $section) = @_;
+
+ # Only try to resolve local links if we're in batch mode and are linking
+ # outside the current document.
+ return $self->SUPER::resolve_pod_page_link(@_)
+ unless $self->batch_mode and $name;
+
+ $section = defined $section
+ ? '#' . $self->idify($section, 1)
+ : '';
+
+ my $local;
+ if ($name =~ /^RT::/) {
+ $local = join "/",
+ map { $self->encode_entities($_) }
+ split /::/, $name;
+ }
+ elsif ($name =~ /^rt-/) {
+ $local = $self->encode_entities($name);
+ }
+
+ if ($local) {
+ # Resolve links correctly by going up
+ my $depth = $self->batch_mode_current_level - 1;
+ return join "/",
+ ($depth ? ".." x $depth : ()),
+ "$local.html$section";
+ } else {
+ return $self->SUPER::resolve_pod_page_link(@_)
+ }
+}
+
1;
commit 99fe0b24ece42897423ea681026fbd8c11b5ea9c
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 13:44:54 2012 -0700
Restore the "back to index" link at the bottom of doc pages
diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 669bd22..7fe2ae0 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -13,7 +13,11 @@ sub new {
sub perldoc_url_prefix { "http://metacpan.org/module/" }
sub html_header { '' }
-sub html_footer { '' }
+sub html_footer {
+ my $self = shift;
+ my $toc = "../" x ($self->batch_mode_current_level - 1);
+ return '<a href="./' . $toc . '">← Back to index</a>';
+}
sub start_Verbatim { $_[0]{'scratch'} = "<pre>" }
sub end_Verbatim { $_[0]{'scratch'} .= "</pre>"; $_[0]->emit; }
commit 612aa5af4f390fb7e119866761821fc5e76b5f92
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 15:03:45 2012 -0700
Generate HTML for the README and UPGRADING docs
It's simply wrapped in <pre> tags, but that's better than nothing.
diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 56e5dfe..1269e37 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -87,10 +87,33 @@ my @dirs = qw(
local/plugins
);
-# Convert each POD file to HTML
-RT::Pod::HTMLBatch->batch_convert( \@dirs, $opts{to} );
+my $converter = RT::Pod::HTMLBatch->new;
+
+# Manually "convert" README* and docs/UPGRADING* to HTML and push them into the
+# known contents.
+for my $file (<README* docs/UPGRADING*>) {
+ (my $name = $file) =~ s{^.+/}{};
+ my $dest = "$opts{to}/$name.html";
+
+ open my $source, "<", $file
+ or warn "Can't open $file: $!", next;
+
+ open my $html, ">", $dest
+ or warn "Can't open $dest: $!", next;
+
+ print $html "<pre>";
+ print $html $_ while <$source>;
+ print $html "</pre>";
+ close $source; close $html;
+
+ $converter->note_for_contents_file([$name], $file, $dest);
+}
+
+# Convert each POD file to HTML
+$converter->batch_convert( \@dirs, $opts{to} );
+exit 0;
__END__
diff --git a/lib/RT/Pod/HTMLBatch.pm b/lib/RT/Pod/HTMLBatch.pm
index 0aa27ae..9b70110 100644
--- a/lib/RT/Pod/HTMLBatch.pm
+++ b/lib/RT/Pod/HTMLBatch.pm
@@ -4,6 +4,8 @@ use warnings;
package RT::Pod::HTMLBatch;
use base 'Pod::Simple::HTMLBatch';
+use List::MoreUtils qw/all/;
+
use RT::Pod::Search;
use RT::Pod::HTML;
@@ -49,6 +51,8 @@ sub write_contents_file {
$name =~ /^RT::Action/ ? '08 Actions' :
$name =~ /^RT::Condition/ ? '09 Conditions' :
$name =~ /^RT(::|$)/ ? '07 Developer Documentation' :
+ $name =~ /^(README|UPGRADING)/ ? '00 Install and Upgrade '.
+ 'Documentation' :
'06 Miscellaneous' ;
if ($section =~ /User/) {
@@ -74,7 +78,17 @@ sub write_contents_file {
print $index "<dt>", esc($section), "</dt>\n";
print $index "<dd>\n";
- for my $page (sort { $a->{name} cmp $b->{name} } @{ $toc{$key} }) {
+ my @sorted = sort {
+ my @names = map { $_->{name} } $a, $b;
+
+ # Sort just the upgrading docs descending within everything else
+ @names = reverse @names
+ if all { /^UPGRADING-/ } @names;
+
+ $names[0] cmp $names[1]
+ } @{ $toc{$key} };
+
+ for my $page (@sorted) {
print $index " <a href='", esc($page->{path}), "'>",
esc($page->{name}),
"</a><br>\n";
commit 6e87dff02385f480c4ed76e847df110fa8838970
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 15:21:32 2012 -0700
Output path must be absolute since we potentially chdir
diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 1269e37..9cbd5f1 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -70,6 +70,9 @@ if ( $opts{'help'} ) {
}
die "--to=DIRECTORY is required\n" unless $opts{to};
+
+$opts{to} = File::Spec->rel2abs($opts{to});
+
make_path( $opts{to} ) unless -e $opts{to};
die "--to MUST be a directory\n" unless -d $opts{to};
commit b32ad6b6b813c53487c70018c813d43c0da18a63
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 15:22:37 2012 -0700
Example for running rt-static-docs locally
diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 9cbd5f1..c1110d6 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -136,10 +136,13 @@ documentation, collects and converts it into a nice set of HTML files, and tops
it off with a helpful index.
Best Practical uses this to publish documentation under
-L<http://bestpractical.com/rt/docs/>. You can run it yourself, however, on
-your local RT and browse the documentation specific to your installation
+L<http://bestpractical.com/rt/docs/>. You can run it yourself, if you'd like,
+on your local RT and browse the documentation specific to your installation
(extensions included!).
+ rt-static-docs --to /opt/rt4/local/html/Documentation/ --rt /opt/rt4
+ # now browse to http://your.rt/Documentation/
+
=head1 OPTIONS
=over
commit 702ba5bccd0976b3ad03c95475fdf7bbcda58b76
Author: Thomas Sibley <trs at bestpractical.com>
Date: Wed Sep 5 15:30:16 2012 -0700
Adjust plugin doc discovery so page names aren't prefixed by a path
By explicitly listing the plugin dirs, the relative filenames used to
generate page names are just like the rest of the doc files.
diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index c1110d6..fb220f1 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -78,7 +78,7 @@ die "--to MUST be a directory\n" unless -d $opts{to};
chdir $opts{rt} if $opts{rt};
-my @dirs = qw(
+my @dirs = (qw(
docs
etc
lib
@@ -87,8 +87,7 @@ my @dirs = qw(
local/lib
local/sbin
local/bin
- local/plugins
-);
+), glob("local/plugins/*/{lib,sbin,bin}"));
my $converter = RT::Pod::HTMLBatch->new;
-----------------------------------------------------------------------
More information about the Rt-commit
mailing list