[Rt-commit] rt branch, 4.0/extension-docs, created. rt-4.0.13-123-g0a56a31

Thomas Sibley trs at bestpractical.com
Wed Jul 3 19:06:55 EDT 2013


The branch, 4.0/extension-docs has been created
        at  0a56a31cda982e4224cdd9e2f0959f05a03109e8 (commit)

- Log -----------------------------------------------------------------
commit cea5e1e5fe222687570430591e9fe9fee65ea53d
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 13:19:44 2013 -0700

    rt-static-docs: Rename --rt to --source
    
    In preparation for processing docs in RT extensions.

diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 30d422d..62aa00e 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -61,7 +61,7 @@ my %opts;
 GetOptions(
     \%opts,
     "help|h",
-    "rt=s",
+    "source=s",
     "to=s",
 );
 
@@ -80,13 +80,13 @@ die "--to MUST be a directory\n"    unless -d $opts{to};
 
 # Unpack the tarball, if that's what we're given.
 my $tmpdir;
-if (($opts{rt} || '') =~ /\.tar\.gz$/ and -f $opts{rt}) {
+if (($opts{source} || '') =~ /\.tar\.gz$/ and -f $opts{source}) {
     $tmpdir = File::Temp->newdir();
 
-    system("tar", "xzpf", $opts{rt}, "-C", $tmpdir);
-    $opts{rt} = <$tmpdir/rt-*>;
+    system("tar", "xzpf", $opts{source}, "-C", $tmpdir);
+    $opts{source} = <$tmpdir/rt-*>;
 }
-chdir $opts{rt} if $opts{rt};
+chdir $opts{source} if $opts{source};
 
 my @dirs = (
     qw(
@@ -187,7 +187,7 @@ rt-static-docs - generate doc shipped with RT
 
 =head1 SYNOPSIS
 
-    rt-static-docs --to /path/to/output [--rt /path/to/rt]
+    rt-static-docs --to /path/to/output [--source /path/to/rt]
 
 =head1 DESCRIPTION
 
@@ -207,7 +207,7 @@ L<http://bestpractical.com/rt/docs/>.
 
 Set the destination directory for the output files.
 
-=item --rt
+=item --source
 
 Set the RT base directory to search under.  Defaults to the current working
 directory, which is fine if you're running this script as

commit 9c5490c05de820643cc231926cf74af0f699a637
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 15:48:46 2013 -0700

    Save what our POD search found and use that info when making local links
    
    If we find a link to an RT resource but didn't find the referenced name
    in the POD search, then assume we're documenting an extension and link
    one level up into rt/.  This allows links in extensions which point to
    core documentation.

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index d220509..6613f47 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -54,6 +54,10 @@ use base 'Pod::Simple::XHTML';
 
 use HTML::Entities qw//;
 
+__PACKAGE__->_accessorize(
+    "batch"
+);
+
 sub new {
     my $self = shift->SUPER::new(@_);
     $self->index(1);
@@ -118,6 +122,8 @@ sub resolve_local_link {
     my $self = shift;
     my ($name, $section) = @_;
 
+    $name .= ""; # stringify name, it may be an object
+
     $section = defined $section
         ? '#' . $self->idify($section, 1)
         : '';
@@ -132,6 +138,7 @@ sub resolve_local_link {
         $local = $self->encode_entities($name);
     }
     elsif ($name eq "RT_Config" or $name eq "RT_Config.pm") {
+        $name  = "RT_Config";
         $local = "RT_Config";
     }
     # These matches handle links that look like filenames, such as those we
@@ -139,6 +146,7 @@ sub resolve_local_link {
     elsif (   $name =~ m{^(?:lib/)(RT/[\w/]+?)\.pm$}
            or $name =~ m{^(?:docs/)(.+?)\.pod$})
     {
+        $name  = join "::", split '/', $1;
         $local = join "/",
                   map { $self->encode_entities($_) }
                 split /\//, $1;
@@ -146,11 +154,20 @@ sub resolve_local_link {
 
     if ($local) {
         # Resolve links correctly by going up
-        my $depth = $self->batch_mode_current_level - 1;
-        return ($depth ? "../" x $depth : "") . "$local.html$section";
+        my $found = $self->batch->found($name);
+        my $depth = $self->batch_mode_current_level;
+        $depth-- if $found;
+        return ($depth ? "../" x $depth : "") . ($found ? "" : "rt/") . "$local.html$section";
     } else {
         return;
     }
 }
 
+sub batch_mode_page_object_init {
+    my ($self, $batch, $module, $infile, $outfile, $depth) = @_;
+    $self->SUPER::batch_mode_page_object_init(@_[1..$#_]);
+    $self->batch( $batch );
+    return $self;
+}
+
 1;
diff --git a/lib/RT/Pod/HTMLBatch.pm b/lib/RT/Pod/HTMLBatch.pm
index f41a43a..a5c3785 100644
--- a/lib/RT/Pod/HTMLBatch.pm
+++ b/lib/RT/Pod/HTMLBatch.pm
@@ -57,6 +57,8 @@ use List::MoreUtils qw/all/;
 use RT::Pod::Search;
 use RT::Pod::HTML;
 
+my $MOD2PATH;
+
 sub new {
     my $self = shift->SUPER::new(@_);
     $self->verbose(0);
@@ -176,4 +178,15 @@ sub esc {
     Pod::Simple::HTMLBatch::esc(@_);
 }
 
+sub find_all_pods {
+    my $self = shift;
+    $MOD2PATH = $self->SUPER::find_all_pods(@_);
+    return $MOD2PATH;
+}
+
+sub found {
+    my ($self, $module) = @_;
+    return(exists $MOD2PATH->{$module} and defined $MOD2PATH->{$module});
+}
+
 1;

commit 8b7db2b6c8ca4f8af1a19f9aa0f7557b79dc7d80
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 16:04:17 2013 -0700

    Fix two POD linking errors uncovered by the new stricter local linking

diff --git a/docs/initialdata.pod b/docs/initialdata.pod
index 6445fb0..c649b62 100644
--- a/docs/initialdata.pod
+++ b/docs/initialdata.pod
@@ -90,7 +90,7 @@ the admin interface.  B<Do not> omit the C<< Domain => 'UserDefined' >> line.
 Additionally, the C<MemberOf> field is specially handled to make it easier to
 add the new group to other groups.  C<MemberOf> may be a single value or an
 array ref.  Each value should be a user-defined group name or hashref to pass
-into L<< RT::Group->LoadByCols >>.  Each group found will have the new group
+into L<RT::Group/LoadByCols>.  Each group found will have the new group
 added as a member.
 
 Unfortunately you can't specify the I<members> of a group at this time.  As a
diff --git a/lib/RT/Action/SendEmail.pm b/lib/RT/Action/SendEmail.pm
index f1c54dd..0ff7e6d 100644
--- a/lib/RT/Action/SendEmail.pm
+++ b/lib/RT/Action/SendEmail.pm
@@ -382,7 +382,7 @@ sub AddAttachments {
 
 =head2 AddAttachment $attachment
 
-Takes one attachment object of L<RT::Attachmment> class and attaches it to the message
+Takes one attachment object of L<RT::Attachment> class and attaches it to the message
 we're building.
 
 =cut

commit ca1239c4c92ef5103dd7a6beb65d329de4a66d24
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 16:12:47 2013 -0700

    Document RT::CustomFieldValues::Groups so links resolve correctly to it

diff --git a/lib/RT/CustomFieldValues/Groups.pm b/lib/RT/CustomFieldValues/Groups.pm
index feeeadb..34722bb 100644
--- a/lib/RT/CustomFieldValues/Groups.pm
+++ b/lib/RT/CustomFieldValues/Groups.pm
@@ -53,10 +53,42 @@ use warnings;
 
 use base qw(RT::CustomFieldValues::External);
 
+=head1 NAME
+
+RT::CustomFieldValues::Groups - Provide RT's groups as a dynamic list of CF values
+
+=head1 SYNOPSIS
+
+To use as a source of CF values, add the following to your F<RT_SiteConfig.pm>
+and restart RT.
+
+    # In RT_SiteConfig.pm
+    Set( @CustomFieldValuesSources, "RT::CustomFieldValues::Groups" );
+
+Then visit the modify CF page in the RT admin configuration.
+
+=head1 METHODS
+
+Most methods are inherited from L<RT::CustomFieldValues::External>, except the
+ones below.
+
+=head2 SourceDescription
+
+Returns a brief string describing this data source.
+
+=cut
+
 sub SourceDescription {
     return 'RT user defined groups';
 }
 
+=head2 ExternalValues
+
+Returns an arrayref containing a hashref for each possible value in this data
+source, where the value name is the group name.
+
+=cut
+
 sub ExternalValues {
     my $self = shift;
 

commit 098bdcc7f92b391a09a290e1da5f19cd15e3327b
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 16:13:45 2013 -0700

    Link the latest core RT docs from non-core docs

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 6613f47..6f4d295 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -157,7 +157,7 @@ sub resolve_local_link {
         my $found = $self->batch->found($name);
         my $depth = $self->batch_mode_current_level;
         $depth-- if $found;
-        return ($depth ? "../" x $depth : "") . ($found ? "" : "rt/") . "$local.html$section";
+        return ($depth ? "../" x $depth : "") . ($found ? "" : "rt/latest/") . "$local.html$section";
     } else {
         return;
     }

commit 8ae031e9b7b61d1749992f38d9f9079100d9e931
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 17:38:50 2013 -0700

    rt-static-docs: Add an --extension flag which doesn't do much (yet)
    
    Currently it just suppresses a warning about not finding ./configure.

diff --git a/devel/tools/rt-static-docs b/devel/tools/rt-static-docs
index 62aa00e..9b619cc 100755
--- a/devel/tools/rt-static-docs
+++ b/devel/tools/rt-static-docs
@@ -63,6 +63,7 @@ GetOptions(
     "help|h",
     "source=s",
     "to=s",
+    "extension=s",
 );
 
 if ( $opts{'help'} ) {
@@ -130,7 +131,8 @@ elsif (-x "configure") {
     generate_configure_help("configure");
 }
 else {
-    warn "Unable to generate a page for ./configure --help!\n";
+    warn "Unable to generate a page for ./configure --help!\n"
+        unless $opts{extension};
 }
 
 # Manually "convert" README* and 3.8-era UPGRADING* to HTML and push them into
@@ -216,6 +218,12 @@ C<devel/tools/rt-static-docs>.
 May also point to a tarball (a file ending in C<.tar.gz>) which will be
 unpacked into a temporary directory and used as the RT base directory.
 
+=item --extension=RTx::Foo
+
+Indicates when C<--source> is an RT extension, such as RT::IR.  Takes an
+extension name for future use, but currently it only acts as a flag to suppress
+a warning about not finding ./configure.
+
 =item --help
 
 Print this help.

commit 7d33c38ca271d86c2c0e9f1b1adcd36cca2ffd35
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Fri Jun 21 17:39:10 2013 -0700

    If we didn't find a local link in the current source, it needs to link even higher up the tree
    
    This accounts for the version component of the docs tree.

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 6f4d295..55abe2d 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -155,8 +155,8 @@ sub resolve_local_link {
     if ($local) {
         # Resolve links correctly by going up
         my $found = $self->batch->found($name);
-        my $depth = $self->batch_mode_current_level;
-        $depth-- if $found;
+        my $depth = $self->batch_mode_current_level
+                  + ($found ? -1 : 1);
         return ($depth ? "../" x $depth : "") . ($found ? "" : "rt/latest/") . "$local.html$section";
     } else {
         return;

commit 980dd65594d9befb1ce092a196769b8328c1bff6
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Jul 1 16:59:01 2013 -0700

    POD links to RT::Extension:: and RT::Authen:: are not local

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 55abe2d..966c761 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -129,7 +129,7 @@ sub resolve_local_link {
         : '';
 
     my $local;
-    if ($name =~ /^RT(::|$)/) {
+    if ($name =~ /^RT(::(?!Extension::|Authen::)|$)/) {
         $local = join "/",
                   map { $self->encode_entities($_) }
                 split /::/, $name;

commit 713e32366cd5992bf3cb55845844d1147dbb7038
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Jul 1 17:07:00 2013 -0700

    Any RT::Extension:: or RT::Authen:: docs we found during this batch _are_ local
    
    This also resolves
        L<Tutorial/Getting started>
    to
        Tutorial.html#Getting-started
    if a Tutorial.pod was found (such as in docs/).

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 966c761..681db87 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -129,7 +129,7 @@ sub resolve_local_link {
         : '';
 
     my $local;
-    if ($name =~ /^RT(::(?!Extension::|Authen::)|$)/) {
+    if ($name =~ /^RT(::(?!Extension::|Authen::)|$)/ or $self->batch->found($name)) {
         $local = join "/",
                   map { $self->encode_entities($_) }
                 split /::/, $name;

commit 9ec0680a872dc9b5971d47046bd80698be78d9ac
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Jul 1 17:23:53 2013 -0700

    Link extension config files when in F<>
    
    This lets F<RTIR_Config.pm> work just like F<RT_Config.pm>.

diff --git a/lib/RT/Pod/HTML.pm b/lib/RT/Pod/HTML.pm
index 681db87..4cde8d6 100644
--- a/lib/RT/Pod/HTML.pm
+++ b/lib/RT/Pod/HTML.pm
@@ -137,9 +137,9 @@ sub resolve_local_link {
     elsif ($name =~ /^rt([-_]|$)/) {
         $local = $self->encode_entities($name);
     }
-    elsif ($name eq "RT_Config" or $name eq "RT_Config.pm") {
-        $name  = "RT_Config";
-        $local = "RT_Config";
+    elsif ($name =~ /^(\w+)_Config(\.pm)?$/) {
+        $name  = "$1_Config";
+        $local = "$1_Config";
     }
     # These matches handle links that look like filenames, such as those we
     # parse out of F<> tags.

commit 0a56a31cda982e4224cdd9e2f0959f05a03109e8
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Jul 1 17:51:42 2013 -0700

    Classify RTIR_Config and other extension configs as install docs
    
    Alongside core RT_Config

diff --git a/lib/RT/Pod/HTMLBatch.pm b/lib/RT/Pod/HTMLBatch.pm
index a5c3785..1c63dcb 100644
--- a/lib/RT/Pod/HTMLBatch.pm
+++ b/lib/RT/Pod/HTMLBatch.pm
@@ -86,7 +86,7 @@ sub classify {
         my %page = @_;
         local $_ = $page{name};
         return 1 if /^(README|UPGRADING)/;
-        return 1 if $_ eq "RT_Config";
+        return 1 if /^RT\w*?_Config$/;
         return 1 if $_ eq "web_deployment";
         return 1 if $page{infile} =~ m{^configure(\.ac)?$};
         return 0;

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


More information about the Rt-commit mailing list