Changeset 1624

Timestamp:

02/03/05 15:17:33 (4 years ago)

Author:

whmoseley

Message:

Fix generation of the docs table of contents.
Add Storable cache for the docs/index.html page
Make bin/build smarter about what needs to be built

Files:

• trunk/swish_website/Plugin/My/POD.pm (modified) (3 diffs)
• trunk/swish_website/bin/build (modified) (17 diffs)
• trunk/swish_website/lib/config/map (modified) (3 diffs)
• trunk/swish_website/lib/pod_toc/index.html (modified) (2 diffs)

trunk/swish_website/Plugin/My/POD.pm

@@ -5 +5 @@
-use base 'Template::Plugin';
-
-use vars '@pod_toc';
-
-my %split_by = map {"head".$_ => 1} 1..4;
-
@@ -12 +10 @@
-
-# *Much* of this is based on (or copied from) Stas' DocSet 0.17
+# This takes a pod file and uses Pod::POM to split it into sections, builds a table
+# of contents and generates the HTML.
+#
+# Will also cache the page's OVERVIEW
+# 
-# I'm not sure why spaces need to be removed from links.  Pod::POM doesn't remove them.
+# Escaping of links and hrefs and name tags needs to be checked.  There was just a discussion
+# on the TT list about escaping hrefs.  Then the xhtml validation rejected % and spaces,
+# so no replace all non-word chars with an underscore.
+#
+# Todo:
+#   might be nice to cache links to make sure there's no duplicates
+#   and also need a way to cross validate links (but can use an external link checker)
-
-sub new {
-    my ( $class, $context, $content ) = @_;
-
-    # How's this for a hack?
-    return \@pod_toc if $content eq 'toc';
-
-    # Grab pod index variable
-    my $stash = $context->stash;
-
-
-
-
+
+
+
+
+
+
+
-    my $pom = $parser->parse_text( $content );
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
@@ -41 +62 @@
-    }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
-    };
-
-
-    $data{view} = 'My::Pod::View::HTML';
-
-
-    return \%data;
-}
+
+
+
+#-----------------------------------------------------------------------------
-
-sub slice_by_head {

trunk/swish_website/bin/build

@@ -4 +4 @@
-use FindBin '$Bin';
-
+
-#=======================================================================
-# Sat Jan  8 06:56:06 PST 2005 - moseley
@@ -10 +11 @@
-# script written by Peter Karman.  Peter made it look to simple, so
-# I rewrote it to make it much more complex.
+#
+# The script exits true (zero) if ANY files are processed.
+#
+# Maintains a cache of table of contents from the pod files so that
+# only changes need to be updated (docs/index.html knows when to get generated)
-#
-# This roughly follows the examples in the Badger book, chapter 11.
@@ -18 +24 @@
-#   might be off in time
-#
+#   Currenly, the download dirs are defined in lib/config/site.
+#   Means can't easily check to see if those pages need to be updated.
+#   Since they don't change often, just do a -all run once a day (to catch
+#   the swish-daily updates).
+#
-#   -src sucks as a name.  Is that the location of the source html files?
-#   No, it's the top-level directory because it expects lib and src
@@ -28 +39 @@
-# List of pod files relative to INCLUDE_PATH
-# swish.css is needed for stand-alone html docs.
+
+
+use vars '$exit_value';
+$exit_value = 1;  # no files processed yet.
-
-my @pod_files = qw(
@@ -133 +148 @@
-    -ignore         = add regex of files to skip.
-
+
+    Script exits false (1) if no files are actually processed.
+    Exits false even if -all -dryrun is used.
+    Exits true is at least one file was processed.
-EOF
-1
+2
-    };
-
@@ -176 +195 @@
-
-
+
+# Build everything here
+
+
+
-my $generator = DocBuilder->new( $config );
-
@@ -186 +210 @@
-
-
-
+ $exit_value
-
-
@@ -207 +231 @@
-use Template;
-use Template::Constants qw( :debug );
+use Storable;  # cache
-
-sub new {
@@ -356 +381 @@
-# Start off using Peter's existing work.  Much easier that way...
-#------------------------------------------------------------------------
+#
-
-sub pods {
-    my ( $self, $pod_files, $key ) = @_;
-
+
-    # Add source directory to INCLUDE_PATH
-
@@ -367 +394 @@
-    unshift @$include_path, $src_dir;
-
+
+
+    # Fetch toc cache from disk
+    my $cache_file = File::Spec->catfile( $self->topdir, 'toc_cache.storable' );
+    my $toc_cache;
+
+    eval { $toc_cache = retrieve( $cache_file ) };
+    warn "Cache file [$cache_file] not found\n" if $@;
+    $toc_cache = {} unless ref $toc_cache eq 'HASH';
+
+
+    # Create sub-cache for this source, if doesn't exist
+    # When processing a pod file the POD plugin will update its own cache entry
+    # in the hash.
+
+    my $this_toc_cache = $toc_cache->{$key} ||= {};
+
+
+
+
+
-    # set where the docs should be written
-    my $out_prefix = $key eq 'swishsrc' ? 'docs' : 'devel/devel_docs';
@@ -372 +420 @@
-    my $version = $self->get_swish_version( $src_dir );
-
+
+    my $update_index = 0;
+
-    for my $in_file ( @$pod_files ) {
-
-        my $out_file = basename( $in_file );
-
-
-
-
+
+
+
+
-        if ( $out_file =~ /\.(pod|pm|pl|cgi)/ ) {
+            $doc_type = 'pod';
-            ($out_file) = map { s/\.in$//; s/\.(pod|pm|pl)$//; lc($_).'.html' } ($out_file);
-            $doc_type = 'pod';
-        }
+
+        # Force processing of every pod if there's not cache entry for it.
+        # And force index.html if any pods were processed
+        # Note that '$in_file' ends up as template.name and is key used by POD plugin
+        my $all = $config->all || 0;
+        $config->{all} = 1 if $out_file eq 'index.html' && $update_index;
+        $config->{all} = 1 if $doc_type eq 'pod' && !$this_toc_cache->{$in_file};
+
-
-        # Set destination directory
@@ -393 +453 @@
-        my $vars = {
-            this => {
-
-
-
-
+    
+    
+    
+   
-                swish_version => $version,
-            },
-
+
+
+
-        };
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-    shift @$include_path;  # remove source dir.
@@ -461 +533 @@
-# generate_website()
-#   Recurses $topsrc/src generating output to $dest
-#   Time stamps are checked unless $config->all
-#   output files match perms on input file
-#
@@ -509 +580 @@
-    $self->process_file( $_, $_ ) for @files;
-
-
+  # Recurse
-}
-
@@ -519 +590 @@
-#   $options  - hash ref of options to add to $vars
-#
+# returns:
+#   true if processed the file (didn't skip for some reason)
+#
-# Checks that input file is newer than output file
-#-------------------------------------------------------------------------
@@ -550 +624 @@
-        $self->logfile('Copy', $in_file, (stat $inpath)[7]);
-        return if $self->config->dryrun;
+
+        $main::exit_value = 0;
-
-        copy( $inpath, $outpath );
@@ -582 +658 @@
-
-    $self->logfile('Process', $in_file, length $capture || (stat $outpath)[7]);
-
+
+
+
-
-    my $mode = $options->{mode} || ( stat $inpath)[2];
-
-    chmod( $mode , $outpath );
+
+    return 1;  # return true if processed a file
-
-}

trunk/swish_website/lib/config/map

@@ -182 +182 @@
-        page    = {
-            daily       = {
-Swish-D
+swish-d
-                tooltip = 'Daily snapshots from CVS'
-            }
@@ -192 +192 @@
-
-            cvs         = {
-CVS
+cvs
-                tooltip     = 'How to build Swish-e from CVS'
-            }
-
-            view_cvs    = {
-View CVS
+view cvs
-                external    = 'http://cvs.sourceforge.net/viewcvs.py/swishe/'
-                tooltip     = 'Go to the SourceForge.net Swish-e CVS Repository'
@@ -211 +211 @@
-        page    = {
-            old     = {
-A
+a
-                tooltip = 'Previous versions'
-            }
-
-            daily = {
-Daily B
+daily b
-                tooltip = 'Daily packages from CVS'
-                file    = 'devel/daily.html'

trunk/swish_website/lib/pod_toc/index.html

@@ -5 +5 @@
-%]
-
-[% USE toc = POD('toc') %]
-
-<!-- noindex -->
@@ -15 +14 @@
-
-<ul class="toc">
-
+
+
+
+
+
-    <li class="top-level">
-        <a href="[% item.page %]">[% item.title %]</a>