File Coverage

lib/Mojolicious/Plugin/DOCRenderer.pm

Criterion	Covered	Total	%
statement	91	96	94.7
branch	11	18	61.1
condition	9	18	50.0
subroutine	16	17	94.1
pod	1	1	100.0
total	128	150	85.3

package Mojolicious::Plugin::DOCRenderer;
use Mojo::Base 'Mojolicious::Plugin';

use File::Basename 'dirname';
use File::Spec::Functions 'catdir';
use Mojo::Asset::File;
use Mojo::ByteStream 'b';
use Mojo::DOM;
use Mojo::URL;
use Mojo::Util qw(slurp unindent url_escape);
use Pod::Simple::HTML;
use Pod::Simple::Search;

our $VERSION = '4.00';

# "Futurama - The One Bright Spot in Your Life!"
sub register {
  my ($self, $app, $conf) = @_;

  # Add "doc" handler
  my $preprocess = $conf->{preprocess} || 'ep';
  $app->renderer->add_handler(
    $conf->{name} || 'doc' => sub {
      my ($renderer, $c, $output, $options) = @_;

      # Preprocess and render
      my $handler = $renderer->handlers->{$preprocess};
      return undef unless $handler->($renderer, $c, $output, $options);
      $$output = _pod_to_html($$output);
      return 1;
    }
  );

  # Append "templates" and "public" directories
  push @{$app->renderer->paths}, catdir(dirname(__FILE__), 'DOCRenderer', 'templates');

  # Doc
  my $url    = $conf->{url}    || '/doc';
  my $module = $conf->{module} || $ENV{MOJO_APP};
  my $defaults = {url => $url, module => $module, format => 'html'};
  return $app->routes->any(
    "$url/:module" => $defaults => [module => qr/[^.]+/] => \&_doc);
}

sub _html {
  my ($self, $src) = @_;

  # Rewrite links
  my $dom = Mojo::DOM->new(_pod_to_html($src));
  my $doc = $self->url_for( $self->param('url') . '/' );
  for my $e ($dom->find('a[href]')->each) {
    my $attrs = $e->attr;
    $attrs->{href} =~ s!%3A%3A!/!gi
      if $attrs->{href} =~ s!^http://search\.cpan\.org/perldoc\?!$doc!;
  }

  # Rewrite code blocks for syntax highlighting and correct indentation
  for my $e ($dom->find('pre')->each) {
    $e->content(my $str = unindent $e->content);
    next if $str =~ /^\s*(?:\$|Usage:)\s+/m || $str !~ /[\$\@\%]\w|->\w/m;
    my $attrs = $e->attr;
    my $class = $attrs->{class};
    $attrs->{class} = defined $class ? "$class prettyprint" : 'prettyprint';
  }

  # Rewrite headers
  my $toc = Mojo::URL->new->fragment('toc');
  my (%anchors, @parts);
  for my $e ($dom->find('h1, h2, h3')->each) {

    # Anchor and text
    my $name = my $text = $e->all_text;
    $name =~ s/\s+/_/g;
    $name =~ s/[^\w\-]//g;
    my $anchor = $name;
    my $i      = 1;
    $anchor = $name . $i++ while $anchors{$anchor}++;

    # Rewrite
    push @parts, [] if $e->type eq 'h1' || !@parts;
    my $link = Mojo::URL->new->fragment($anchor);
    push @{$parts[-1]}, $text, $link;
    my $permalink = $self->link_to('#' => $link, class => 'permalink');
    $e->content($permalink . $self->link_to($text => $toc, id => $anchor));
  }

  # Try to find a title
  my $title = 'Doc';
  $dom->find('h1 + p')->first(sub { $title = shift->text });

  # Combine everything to a proper response
  $self->content_for(doc => "$dom");
  $self->render(title => $title, parts => \@parts);
}

sub _doc {
  my $self = shift;

  # Find module or redirect to CPAN
  my $module = $self->param('module');
  $module =~ s!/!::!g;
  my $path
    = Pod::Simple::Search->new->find($module, map { $_, "$_/pods" } @INC);
  return $self->redirect_to("http://metacpan.org/module/$module")
    unless $path && -r $path;

  my $src = slurp $path;
  $self->respond_to(txt => {data => $src}, any => sub { _html($self, $src) });
}

sub _pod_to_html {
  return '' unless defined(my $pod = ref $_[0] eq 'CODE' ? shift->() : shift);

  my $parser = Pod::Simple::HTML->new;
  $parser->$_('') for qw(force_title html_header_before_title);
  $parser->$_('') for qw(html_header_after_title html_footer);
  $parser->output_string(\(my $output));
  return $@ unless eval { $parser->parse_string_document("$pod"); 1 };

  # Filter
  $output =~ s!\n!!g;
  $output =~ s!(.*?)!$1!sg;

  return $output;
}

1;

=encoding utf8

=head1 NAME

Mojolicious::Plugin::DOCRenderer - Doc Renderer Plugin

=head1 SYNOPSIS

  # Mojolicious::Lite
  plugin 'DOCRenderer';
  plugin DOCRenderer => {module => 'MyApp'};
  plugin DOCRenderer => {name => 'foo'};
  plugin DOCRenderer => {url => '/mydoc'};
  plugin DOCRenderer => {preprocess => 'epl'};

  # Mojolicious
  $self->plugin('DOCRenderer');
  $self->plugin(DOCRenderer => {module => 'MyApp'});
  $self->plugin(DOCRenderer => {name => 'foo'});
  $self->plugin(DOCRenderer => {url => '/mydoc'});
  $self->plugin(DOCRenderer => {preprocess => 'epl'});

  #############################
  # Mojolicious::Lite example #
  #############################
  use Mojolicious::Lite;
  use File::Basename;

  plugin 'DOCRenderer' => {
      # use this script base name as a default module to show for "/doc"
      module => fileparse( __FILE__, qr/\.[^.]*/ );
  };

  app->start;

  __END__

  =head1 NAME

  MyApp - My Mojolicious::Lite Application

=head1 DESCRIPTION

  This documentation will be available online, for example from L.

  =cut

  #######################
  # Mojolicious example #
  #######################
  package MyApp;
  use Mojo::Base 'Mojolicious';

  sub development_mode {
    # Enable browsing of "/doc" only in development mode
    shift->plugin( 'DOCRenderer' );
  }

  sub startup {
    my $self = shift;
    # some code
  }

  __END__

  =head1 NAME

  MyApp - My Mojolicious Application

  =head1 DESCRIPTION

  This documentation will be available online, for example from L.

  =cut

=head1 DESCRIPTION

L generates on-the-fly and browses online
POD documentation directly from your Mojolicious application source codes
and makes it available under I (customizable).

The plugin expects that you use POD to document your codes of course.

The plugin is simple modification of L.

=head1 OPTIONS

=head2 C

  # Mojolicious::Lite
  plugin DOCRenderer => {module => 'MyApp'};

Name of the module to initially display. Default is C<$ENV{MOJO_APP}>.
Mojolicious::Lite application may have undefined C<$ENV{MOJO_APP}>; in such
case you should set C, see Mojolicious::Lite example.

=head2 C

  # Mojolicious::Lite
  plugin DOCRenderer => {name => 'foo'};

Handler name.

=head2 C

  # Mojolicious::Lite
  plugin DOCRenderer => {preprocess => 'epl'};

Handler name of preprocessor.

=head2 C

  # Mojolicious::Lite
  plugin DOCRenderer => {url => '/mydoc'};

URL from which the documentation of your project is available. Default is I.

=head1 METHODS

L inherits all methods from
L and implements the following new ones.

=head2 C

  my $route = $plugin->register(Mojolicious->new);
  my $route = $plugin->register(Mojolicious->new, {name => 'foo'});

Register renderer in L application.

=head1 SEE ALSO

L, L, L, L.

=cut