Allow the user specify which file to parse for POD

lib/Dist/Zilla/Plugin/Readme/Brief.pm

@@ -25,6 +25,44 @@ my %installers = (
   'mb'   => '_install_mb',
 );
 
+=attr source_file
+
+Determines the file that will be parsed for POD to populate the README from.
+
+By default, it uses your C<main_module>, except if you have a C<.pod> file with
+the same basename and path as your C<main_module>, in which case it uses that.
+
+=cut
+
+has _source_file_override => (
+  isa => 'Str',
+  is  => 'ro' ,
+  init_arg  => 'source_file',
+  predicate => '_has_source_file_override',
+);
+
+has source_file => (
+  is   => 'ro',
+  isa  => 'Dist::Zilla::Role::File',
+  lazy => 1,
+  init_arg => undef,
+  default  => sub {
+    my ( $self ) = @_;
+    my $file = $self->_has_source_file_override
+      ? first { $_->name eq $self->_source_file_override } @{ $self->zilla->files }
+      : do {
+        my $main_module = $self->zilla->main_module;
+        my $alt = $main_module->name;
+        my $pod = ( $alt =~ s/\.pm\z/.pod/ ) && first { $_->name eq $alt } @{ $self->zilla->files };
+        $pod or $main_module;
+      };
+    $self->log_fatal( 'Unable to find source_file in the distribution' ) if not $file;
+    $self->log_debug( 'Using POD from ' . $file->name ) unless $self->_has_source_file_override;
+    return $file;
+  },
+);
+
+
 =attr installer
 
 Determines what installers to document in the C<INSTALLATION> section.
@@ -157,15 +195,10 @@ sub _configured_installer {
   return join qq[\nor\n\n], @sections;
 }
 
-sub _source_pm_file {
-  my ($self) = @_;
-  return $self->zilla->main_module;
-}
-
 sub _source_pod {
   my ($self) = @_;
   return $self->{_pod_cache} if exists $self->{_pod_cache};
-  my $chars = $self->_source_pm_file->content;
+  my $chars = $self->source_file->content;
 
   require Encode;
   require Pod::Elemental;
@@ -206,7 +239,7 @@ sub _podtext_nodes {
 sub _heading {
   my ($self) = @_;
   require PPI::Document;    # Historic version of dzil doesn't load PPI on its own...
-  my $document = $self->ppi_document_for_file( $self->_source_pm_file );
+  my $document = $self->ppi_document_for_file( $self->source_file );
   return PPIx::DocumentName->extract($document);
 }
 
@@ -225,7 +258,7 @@ sub _description {
     push @found, $nodes[$node_number];
   }
   if ( not @found ) {
-    $self->log( 'DESCRIPTION not found in ' . $self->_source_pm_file->name );
+    $self->log( 'DESCRIPTION not found in ' . $self->source_file->name );
     return q[];
   }
   return $self->_podtext_nodes( map { @{ $_->children } } @found );
@@ -254,7 +287,7 @@ sub _copyright_from_pod {
     push @found, $nodes[$node_number];
   }
   if ( not @found ) {
-    $self->log( 'COPYRIGHT/LICENSE not found in ' . $self->_source_pm_file->name );
+    $self->log( 'COPYRIGHT/LICENSE not found in ' . $self->source_file->name );
     return;
   }
   return $self->_podtext_nodes(@found);
@@ -310,9 +343,9 @@ However, bugs are highly likely to be encountered, especially as there are no te
 
 =over 4
 
-=item * Heading is derived from the C<package> statement in C<main_module>
+=item * Heading is derived from the C<package> statement in the C<source_file>
 
-=item * Description is extracted as the entire C<H1Nest> of the section titled C<DESCRIPTION> in C<main_module>
+=item * Description is extracted as the entire C<H1Nest> of the section titled C<DESCRIPTION> in the C<source_file>
 
 =item * Installation instructions are automatically determined by the presence of either
 
@@ -328,7 +361,7 @@ However, bugs are highly likely to be encountered, especially as there are no te
 
 =back
 
-=item * I<ALL> Copyright and license details are extracted from C<main_module> in any C<H1Nest> that has either C<COPYRIGHT> or C<LICENSE> in the heading.
+=item * I<ALL> Copyright and license details are extracted from the C<source_file> in any C<H1Nest> that has either C<COPYRIGHT> or C<LICENSE> in the heading.
 
 =item * Or failing such a section, a C<COPYRIGHT AND LICENSE> section will be derived from C<< zilla->license >>
 
@@ -364,7 +397,7 @@ and contains no installation instructions.
 
 =item * L<< C<[ReadmeFromPod]>|Dist::Zilla::Plugin::ReadmeFromPod >>
 
-Provides various output formats, but ultimately is a transformer of your C<main_module>'s C<POD>,
+Provides various output formats, but ultimately is a transformer of your C<source_file>'s C<POD>,
 which is excessive for some peoples tastes. ( And lacks install instructions )
 
 =item * L<< C<[ReadmeAnyFromPod]>|Dist::Zilla::Plugin::ReadmeAnyFromPod >>

t/pod_file.t

@@ -0,0 +1,41 @@
+use strict;
+use warnings;
+
+use Test::More;
+
+# ABSTRACT: Basic Test for documentation in .pod
+
+use Dist::Zilla::Util::Test::KENTNL 1.004 qw( dztest );
+use Test::DZil qw( simple_ini );
+
+my $test = dztest();
+$test->add_file( 'lib/Example.pm' => 1 );
+$test->add_file( 'lib/Example.pod' => <<'EOF' );
+
+# PODNAME: Foo
+
+=head1 DESCRIPTION
+
+This is a description
+
+=cut
+
+1;
+
+EOF
+
+$test->add_file( 'dist.ini' => simple_ini( [ 'GatherDir' => {} ], [ 'Readme::Brief' => {} ], ) );
+$test->build_ok;
+
+my $src_file = $test->test_has_built_file('README');
+my @lines = $src_file->lines_utf8( { chomp => 1 } );
+
+use List::Util qw( first );
+
+ok( ( first { $_ eq 'Foo' } @lines ), 'Document name found and injected' );
+ok( ( first { $_ eq 'This is a description' } @lines ), 'Description injected' );
+ok( ( first { $_ eq 'INSTALLATION' } @lines ), 'Installation section injected' );
+ok( ( first { $_ eq 'COPYRIGHT AND LICENSE' } @lines ), 'Copyright section injected' );
+
+done_testing;
+

t/source_file.t

@@ -0,0 +1,41 @@
+use strict;
+use warnings;
+
+use Test::More;
+
+# ABSTRACT: Basic Test
+
+use Dist::Zilla::Util::Test::KENTNL 1.004 qw( dztest );
+use Test::DZil qw( simple_ini );
+
+my $test = dztest();
+$test->add_file( 'lib/Example.pm' => 1 );
+$test->add_file( 'bazinga.pod' => <<'EOF' );
+
+package Foo;
+
+=head1 DESCRIPTION
+
+This is a description
+
+=cut
+
+1;
+
+EOF
+
+$test->add_file( 'dist.ini' => simple_ini( [ 'GatherDir' => {} ], [ 'Readme::Brief' => { source_file => 'bazinga.pod' } ], ) );
+$test->build_ok;
+
+my $src_file = $test->test_has_built_file('README');
+my @lines = $src_file->lines_utf8( { chomp => 1 } );
+
+use List::Util qw( first );
+
+ok( ( first { $_ eq 'Foo' } @lines ), 'Document name found and injected' );
+ok( ( first { $_ eq 'This is a description' } @lines ), 'Description injected' );
+ok( ( first { $_ eq 'INSTALLATION' } @lines ), 'Installation section injected' );
+ok( ( first { $_ eq 'COPYRIGHT AND LICENSE' } @lines ), 'Copyright section injected' );
+
+done_testing;
+