diff --git a/lib/Dist/Zilla/Plugin/Readme/Brief.pm b/lib/Dist/Zilla/Plugin/Readme/Brief.pm index a3097ef..4a29855 100644 --- a/lib/Dist/Zilla/Plugin/Readme/Brief.pm +++ b/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, except if you have a C<.pod> file with +the same basename and path as your C, 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 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 statement in C +=item * Heading is derived from the C statement in the C -=item * Description is extracted as the entire C of the section titled C in C +=item * Description is extracted as the entire C of the section titled C in the C =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 Copyright and license details are extracted from C in any C that has either C or C in the heading. +=item * I Copyright and license details are extracted from the C in any C that has either C or C in the heading. =item * Or failing such a section, a C 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's C, +Provides various output formats, but ultimately is a transformer of your C's C, which is excessive for some peoples tastes. ( And lacks install instructions ) =item * L<< C<[ReadmeAnyFromPod]>|Dist::Zilla::Plugin::ReadmeAnyFromPod >> diff --git a/t/pod_file.t b/t/pod_file.t new file mode 100644 index 0000000..3c77cab --- /dev/null +++ b/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; + diff --git a/t/source_file.t b/t/source_file.t new file mode 100644 index 0000000..55221b0 --- /dev/null +++ b/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; +