ASPEER-MakeMaker-Markdown-Pod

 view release on metacpan or  search on metacpan

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN


#======================================================================================================================

#  Makefile targets from here down
#
sub doc {


    #  Convert DocBook articles under doc to sibling Markdown files
    #
    my ($self, $param_hr)=(shift(), arg(@_));
    msg($self);
    if (-d 'doc') {
        require Docbook::Convert::Pandoc;
        my $docbook_or=Docbook::Convert::Pandoc->new();
        my $changed_fn_ar=$docbook_or->convert_articles('doc');
        msg('docbook: %s: updated', $_) foreach @{$changed_fn_ar};
    }


    #  Convert MD files to POD
    #
    my $exe_files_ar=$param_hr->{'EXE_FILES_AR'};
    my %exe_files=map {$_ => 1} @{$exe_files_ar};
    require Markdown::Pod::Embed;


    #  Get manifest - only convert files in manifest
    #
    require ExtUtils::Manifest;
    my $manifest_hr=ExtUtils::Manifest::maniread();


    #  Hash to hold files we generate so not processed twice
    #
    my %ignore_fn;


    #  Look for all Markdown files ignoring ones we created ourselves
    #
    my @manifest_md_fn=sort grep {/\.md$/ && !m{^t/}} keys %{$manifest_hr};
    @manifest_md_fn=grep    {!$ignore_fn{$_}} @manifest_md_fn;


    #  Iterate
    #
    foreach my $fn (@manifest_md_fn) {

        #  Get target file name. If foo.pm.md, bar.pl.md and foo.pm or bar.pl exists, then
        #  convert Markdown to POD and install into target file.
        #

        #
        (my $target_fn=$fn)=~s/\.md$//;

        if ($target_fn=~/\.pm$/ || $target_fn=~/\.pl$/ || $exe_files{$target_fn}) {
            unless (-f $target_fn) {
                verbose("markpod: %s -> %s: skipped, missing target", $fn, $target_fn);
                next;
            }
            msg("markpod: %s -> %s: starting merge", $fn, $target_fn);
            my $markpod_or=Markdown::Pod::Embed->new();
            my $pod_changed=$markpod_or->markpod_process_and_update($target_fn);
            if (!defined $pod_changed) {
                msg("markpod: %s -> %s: finished, skipped", $fn, $target_fn);
            }
            elsif ($pod_changed) {
                msg("markpod: %s -> %s: finished, updated pod", $fn, $target_fn);
            }
            else {
                msg("markpod: %s -> %s: finished, no changes", $fn, $target_fn);
            }
        }
        else {
            verbose("markpod: %s -> %s: skipped, unsupported target", $fn, $target_fn);

        }

    }


    #  Done
    #
    return undef;

}


sub readme {


    #  Build README files from README.md or VERSION_FROM markdown
    #
    my ($self, $param_hr)=(shift(), arg(@_));
    require Markdown::Pod::Embed;


    #  Get manifest for any file additions we make
    #
    require ExtUtils::Manifest;
    my $manifest_hr=ExtUtils::Manifest::maniread();
    my @manifest_add;
    my $version_from_fn=$param_hr->{'VERSION_FROM'};
    my $readme_md_fn='README.md';
    my $readme_fn='README';
    my $markpod_or=Markdown::Pod::Embed->new();
    my $md;
    my $source_fn;


    #  Use an existing Markdown README when one is available
    #
    if (-f $readme_md_fn) {
        $source_fn=$readme_md_fn;
        $md=slurp($readme_md_fn);
    }
    elsif (-e $readme_md_fn || -l $readme_md_fn) {
        return err("$readme_md_fn exists and is not a regular file");
    }
    elsif (-e $readme_fn || -l $readme_fn) {
        verbose('markpod: %s exists without %s, leaving both unchanged', $readme_fn, $readme_md_fn);
        return undef;
    }
    else {
        unless (defined $version_from_fn && length $version_from_fn) {
            verbose('markpod: no VERSION_FROM file, no README files created');
            return undef;
        }
        $md=$markpod_or->markpod_markdown_source($version_from_fn);
        unless (defined $md && length $md) {
            msg('markpod: %s -> %s: skipped, no markdown source', $version_from_fn, $readme_fn);
            return undef;
        }
        my $readme_md=$md;
        $readme_md.=$/ unless $readme_md=~/\n\z/;
        blurp($readme_md_fn, $readme_md) ||
            return err();
        push @manifest_add, $readme_md_fn unless exists $manifest_hr->{$readme_md_fn};
        $source_fn=$readme_md_fn;
    }
    msg('markpod: %s -> %s: starting render', $source_fn, $readme_fn);


    #  No markdown means nothing to render
    #
    unless (defined $md && length $md) {
        msg('markpod: %s -> %s: finished, skipped empty markdown source', $source_fn, $readme_fn);
        manifest_add(\@manifest_add) if @manifest_add;
        return undef;
    }


    #  Convert markdown to text
    #
    my $text=$markpod_or->markpod_markdown_text($md);


    #  Update README only when changed
    #
    my $existing_readme=-f $readme_fn ? slurp($readme_fn) : '';
    if (md5_hex($existing_readme) ne md5_hex($text)) {
        $markpod_or->outfile($text, $readme_fn) ||
            return err();
        msg('markpod: %s -> %s: finished, updated', $source_fn, $readme_fn);
    }
    else {
        msg('markpod: %s -> %s: finished, no changes', $source_fn, $readme_fn);
    }

    push @manifest_add, $readme_fn unless exists $manifest_hr->{$readme_fn};
    manifest_add(\@manifest_add) if @manifest_add;

}


sub manifest_add {

    my ($file_ar)=@_;
    return undef unless @{$file_ar};
    require ExtUtils::Manifest;
    my %add=map { $_ => '' } @{$file_ar};
    ExtUtils::Manifest::maniadd(\%add);
    return 1;

}


1;


__END__

=begin markdown

# NAME

ASPEER::MakeMaker::Markdown::Pod::MM - MakeMaker integration for ASPEER::MakeMaker::Markdown::Pod

# SYNOPSIS

In `Makefile.PL`:

```perl
BEGIN {
    use lib './lib';
    eval {
        require ASPEER::MakeMaker::Markdown::Pod;
        ASPEER::MakeMaker::Markdown::Pod->import;
        1;
    };
}
```

Then run:

```bash
perl Makefile.PL
make doc
make readme
```

# DESCRIPTION

`ASPEER::MakeMaker::Markdown::Pod::MM` generates and executes the documentation targets
used by `ExtUtils::MakeMaker`. DocBook article conversion is delegated to
`Docbook::Convert::Pandoc`. Markdown source selection, Markdown-to-POD conversion,
and Perl source updates are delegated to `Markdown::Pod::Embed`.

This class inherits the common MakeMaker namespace from
`ASPEER::MakeMaker::MM` and imports shared helper functions from
`ASPEER::MakeMaker::MM::Util`.

`ASPEER::MakeMaker::MM::Import` installs the MakeMaker lifecycle hooks and
appends the target template. This module handles the resulting `doc` and
`readme` invocations.

# MAKEFILE INTEGRATION

The module adds a postamble fragment containing targets that invoke
`ASPEER::MakeMaker::Markdown::Pod::MM` from the generated Makefile.

`doc`
: Recursively converts DocBook article XML beneath `doc/` to sibling Markdown
  files without using `MANIFEST` as a discovery list. It then finds Markdown
  files listed in `MANIFEST`, derives each target by removing the trailing
  `.md`, and merges supported sidecars into matching `.pm`, `.pl`, or executable
  files. Markdown files under `t/` are ignored so test fixtures are not rewritten.

`readme`
: Builds `README` from the best available Markdown source.

The generated status output is concise and goes to STDERR:

```text
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
```

Unsupported or missing targets are reported only when verbose output has been
enabled.

# README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

1. If `README.md` exists, it is used to generate or update `README`.
2. If `README` exists without `README.md`, both are left unchanged.
3. If neither exists, Markdown is obtained from the sidecar or embedded
   documentation of the file named by `VERSION_FROM` and written to a new,
   regular `README.md` file. `README` is then rendered from that file.
4. If the `VERSION_FROM` file has no sidecar or embedded Markdown, no README
   file is created.

The module never creates a `VERSION_FROM.md` sidecar. Generated README files are
added to `MANIFEST`.

`Markdown::Pod::Embed` renders the Markdown to plain text with `pandoc`.

# FUNCTIONS

## arg

Converts the positional arguments passed through the generated Makefile target
into a named hash used by `doc` and `readme`.

## doc

Converts DocBook article XML beneath `doc/` to sibling Markdown files, then
processes sidecar Markdown files from `MANIFEST` and updates supported Perl
targets in place.

## readme

Renders the project README from Markdown according to the precedence described
above.

## manifest_add

Adds generated support files to `MANIFEST`.

# CAVEATS

This module contains MakeMaker-specific target execution. Hook installation is
provided by `ASPEER::MakeMaker::MM::Import`, and Markdown/POD processing is
isolated in `Markdown::Pod::Embed`.

The implementation expects a traditional MakeMaker distribution layout with a
usable `MANIFEST` file.

# SEE ALSO

`ASPEER::MakeMaker::Markdown::Pod`, `ASPEER::MakeMaker::MM::Import`,
`Markdown::Pod::Embed`, `ExtUtils::MakeMaker`, `ExtUtils::Manifest`

# AUTHOR

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN


=head1 NAME

ASPEER::MakeMaker::Markdown::Pod::MM - MakeMaker integration for ASPEER::MakeMaker::Markdown::Pod


=head1 SYNOPSIS

In C<Makefile.PL>:


 BEGIN {
     use lib './lib';
     eval {
         require ASPEER::MakeMaker::Markdown::Pod;
         ASPEER::MakeMaker::Markdown::Pod->import;
         1;
     };
 }
Then run:


 perl Makefile.PL
 make doc
 make readme

=head1 DESCRIPTION

C<ASPEER::MakeMaker::Markdown::Pod::MM> generates and executes the documentation targets
used by C<ExtUtils::MakeMaker>. DocBook article conversion is delegated to
C<Docbook::Convert::Pandoc>. Markdown source selection, Markdown-to-POD conversion,
and Perl source updates are delegated to C<Markdown::Pod::Embed>.

This class inherits the common MakeMaker namespace from
C<ASPEER::MakeMaker::MM> and imports shared helper functions from
C<ASPEER::MakeMaker::MM::Util>.

C<ASPEER::MakeMaker::MM::Import> installs the MakeMaker lifecycle hooks and
appends the target template. This module handles the resulting C<doc> and
C<readme> invocations.


=head1 MAKEFILE INTEGRATION

The module adds a postamble fragment containing targets that invoke
C<ASPEER::MakeMaker::Markdown::Pod::MM> from the generated Makefile.

C<doc>
: Recursively converts DocBook article XML beneath C<doc/> to sibling Markdown
  files without using C<MANIFEST> as a discovery list. It then finds Markdown
  files listed in C<MANIFEST>, derives each target by removing the trailing
  C<.md>, and merges supported sidecars into matching C<.pm>, C<.pl>, or executable
  files. Markdown files under C<t/> are ignored so test fixtures are not rewritten.

C<readme>
: Builds C<README> from the best available Markdown source.

The generated status output is concise and goes to STDERR:


 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: starting merge
 markpod: lib/My/Module.pm.md -> lib/My/Module.pm: finished, updated pod
Unsupported or missing targets are reported only when verbose output has been
enabled.


=head1 README SOURCE PRECEDENCE

README generation observes the existing project files before creating anything:

=over

=item 1.

If C<README.md> exists, it is used to generate or update C<README>.


=item 2.

If C<README> exists without C<README.md>, both are left unchanged.


=item 3.

If neither exists, Markdown is obtained from the sidecar or embedded
   documentation of the file named by C<VERSION_FROM> and written to a new,
   regular C<README.md> file. C<README> is then rendered from that file.


=item 4.

If the C<VERSION_FROM> file has no sidecar or embedded Markdown, no README
   file is created.


=back

The module never creates a C<VERSION_FROM.md> sidecar. Generated README files are
added to C<MANIFEST>.

C<Markdown::Pod::Embed> renders the Markdown to plain text with C<pandoc>.


=head1 FUNCTIONS


=head2 arg

Converts the positional arguments passed through the generated Makefile target
into a named hash used by C<doc> and C<readme>.


=head2 doc

Converts DocBook article XML beneath C<doc/> to sibling Markdown files, then
processes sidecar Markdown files from C<MANIFEST> and updates supported Perl
targets in place.


=head2 readme



( run in 0.629 second using v1.01-cache-2.11-cpan-234fa220139 )