[Rt-commit] rt branch, 4.0/static-docs, updated. rt-4.0.6-314-g7f9b93f

Jim Brandt jbrandt at bestpractical.com
Tue Aug 28 15:05:02 EDT 2012


The branch, 4.0/static-docs has been updated
       via  7f9b93f74bb99efeef11f64a37117928a4f775ac (commit)
      from  269602f9a2e3f7031d73dab7006a9cdb0c49d573 (commit)

Summary of changes:
 devel/tools/rt-static-docs           |  22 +++-
 lib/RT/Pod/Simple/HTMLBatch.pm       | 236 +++++++++++++++++++++++++++++++++++
 share/html/Documentation/rt-docs.css |  14 +++
 3 files changed, 268 insertions(+), 4 deletions(-)
 create mode 100644 lib/RT/Pod/Simple/HTMLBatch.pm
 create mode 100644 share/html/Documentation/rt-docs.css

- Log -----------------------------------------------------------------
commit 7f9b93f74bb99efeef11f64a37117928a4f775ac
Author: Jim Brandt <jbrandt at bestpractical.com>
Date:   Tue Aug 28 14:59:06 2012 -0400

    Generate TOC and HTML from pod in additional RT directories
    
    Generate HTML from pod in docs, sbin, and bin in addition to
    lib.
    
    Subclass Pod::Simple::HTMLBatch to create docs from utilities
    in bin and sbin and to create a custom TOC with documentation
    sections.

diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 356a8c4..4eb027d 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -52,7 +52,7 @@ use warnings;
 
 use Getopt::Long;
 use File::Basename 'basename';
-use Pod::Simple::HTMLBatch;
+use RT::Pod::Simple::HTMLBatch;
 
 my %opts;
 GetOptions( \%opts, "help|h", 'rt-root=s', 'to=s' );
@@ -73,10 +73,22 @@ if ( $opts{'rt-root'} ) {
     chdir $opts{'rt-root'};
 }
 
-my @dirs = ( 'docs', 'lib' );
+my @dirs = ( 'docs', 'lib', 'bin', 'sbin' );
 
-my $batch = Pod::Simple::HTMLBatch->new;
-$batch->contents_page_start('');
+my $batch = RT::Pod::Simple::HTMLBatch->new;
+$batch->css_flurry(0);
+$batch->add_css('rt-docs.css');
+
+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
+
+$batch->contents_page_start($contents_page_start);
 $batch->contents_page_end('');
 $batch->batch_convert( join( ':', @dirs ), $opts{to} );
 
@@ -90,6 +102,8 @@ rt-static-docs - generate doc shipped with RT
 
     rt-static-docs --rt-root /path/to/rt --to /path/to/output
 
+    perl -Ilib devel/tools/rt-static-docs --to share/html/Documentation
+
 =head1 DESCRIPTION
 
 This script is used to generate documents shipped with RT.
diff --git a/lib/RT/Pod/Simple/HTMLBatch.pm b/lib/RT/Pod/Simple/HTMLBatch.pm
new file mode 100644
index 0000000..a72e9c3
--- /dev/null
+++ b/lib/RT/Pod/Simple/HTMLBatch.pm
@@ -0,0 +1,236 @@
+# BEGIN BPS TAGGED BLOCK {{{
+#
+# COPYRIGHT:
+#
+# This software is Copyright (c) 1996-2012 Best Practical Solutions, LLC
+#                                          <sales at bestpractical.com>
+#
+# (Except where explicitly superseded by other copyright notices)
+#
+#
+# LICENSE:
+#
+# This work is made available to you under the terms of Version 2 of
+# the GNU General Public License. A copy of that license should have
+# been provided with this software, but in any event can be snarfed
+# from www.gnu.org.
+#
+# This work is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301 or visit their web page on the internet at
+# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
+#
+#
+# CONTRIBUTION SUBMISSION POLICY:
+#
+# (The following paragraph is not intended to limit the rights granted
+# to you to modify and distribute this software under the terms of
+# the GNU General Public License and is only of importance to you if
+# you choose to contribute your changes and enhancements to the
+# community by submitting them to Best Practical Solutions, LLC.)
+#
+# By intentionally submitting any modifications, corrections or
+# derivatives to this work, or any other work intended for use with
+# Request Tracker, to Best Practical Solutions, LLC, you confirm that
+# you are the copyright holder for those contributions and you grant
+# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
+# royalty-free, perpetual, license to use, copy, create derivative
+# works based on those contributions, and sublicense and distribute
+# those contributions and any derivatives thereof.
+#
+# END BPS TAGGED BLOCK }}}
+
+package RT::Pod::Simple::HTMLBatch;
+use base Pod::Simple::HTMLBatch;
+
+=over
+
+Override to 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;
+}
+
+=over
+
+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\// ) {
+            $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;
+}
+
+=over
+
+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_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});
+    }
+}
+
+=over
+
+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 format_link_text
+
+Apply some formatting to the visible links for user documentation.
+
+=cut
+
+sub format_link_text {
+    my ($self, $content) = @_;
+
+    foreach my $entry ( @{$content} ){
+        $entry->[0] =~ s/_/ /g;
+        $entry->[0] = join '/', map {ucfirst} split /::/, $entry->[0];
+    }
+
+}
+
+1;
diff --git a/share/html/Documentation/rt-docs.css b/share/html/Documentation/rt-docs.css
new file mode 100644
index 0000000..72548d5
--- /dev/null
+++ b/share/html/Documentation/rt-docs.css
@@ -0,0 +1,14 @@
+body {
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-size: 76%;
+    margin: 10px;
+}
+dt{
+  border-bottom: 1px solid black;
+  font-size: 150%;
+}
+
+a {
+  color:#0065ce;
+  display: block;
+}

-----------------------------------------------------------------------


More information about the Rt-commit mailing list