maint/gen_pod_inherit

   1 #!/usr/bin/env perl
   2
   3 use warnings;
   4 use strict;
   5
   6 use DBIx::Class::_Util; # load early in case any shims are needed
   7
   8 my $lib_dir = 'lib';
   9 my $pod_dir = 'maint/.Generated_Pod';
  10
  11 my $result_metapod_fn = "$lib_dir/DBIx/Class/Manual/ResultClass.pod";
  12
  13 die "POD generator must be executed from the dist root\n"
  14   unless -d $lib_dir and -d $pod_dir;
  15
  16 require File::Copy;
  17 File::Copy::copy(
  18   "$result_metapod_fn.proto",
  19   "$result_metapod_fn",
  20 ) or die "Copying ResultClass proto pod ($result_metapod_fn) failed: $!";
  21
  22 # cleanup
  23 END {
  24   local ($@, $!, $?);
  25   unlink $result_metapod_fn;
  26 }
  27
  28 require Pod::Inherit;
  29
  30 Pod::Inherit->new({
  31    input_files       => $lib_dir,
  32    out_dir           => "$pod_dir/lib",
  33    force_permissions => 1,
  34    class_map         => {
  35       "DBIx::Class::Relationship::HasMany"    => "DBIx::Class::Relationship",
  36       "DBIx::Class::Relationship::HasOne"     => "DBIx::Class::Relationship",
  37       "DBIx::Class::Relationship::BelongsTo"  => "DBIx::Class::Relationship",
  38       "DBIx::Class::Relationship::ManyToMany" => "DBIx::Class::Relationship",
  39       "DBIx::Class::ResultSourceProxy"        => "DBIx::Class::ResultSource",
  40    },
  41    # skip the deprecated classes that give out *DEPRECATED* warnings
  42    skip_classes      => [ qw(
  43       lib/DBIx/Class/Storage/DBI/Sybase/MSSQL.pm
  44       lib/DBIx/Class/Serialize/Storable.pm
  45       lib/DBIx/Class/ResultSetManager.pm
  46       lib/DBIx/Class/InflateColumn/File.pm
  47       lib/DBIx/Class/DB.pm
  48       lib/DBIx/Class/CDBICompat/
  49       lib/DBIx/Class/CDBICompat.pm
  50       lib/DBIx/Class/_TempExtlib/
  51    ),
  52    # skip the ::Storage:: family for now
  53    qw(
  54       lib/DBIx/Class/Storage/
  55       lib/DBIx/Class/Storage.pm
  56    ),
  57       'lib/DBIx/Class/Storage/DBI/Replicated/Pool.pm',  # this one just errors out with: The 'add_attribute' method cannot be called on an immutable instance
  58       'lib/DBIx/Class/Relationship.pm',                 # it already documents its own inheritors
  59       'lib/DBIx/Class/Core.pm',                         # we actually don't want this populated in favor of redirecting users to the ResultClass docs
  60       'lib/DBIx/Class/Optional/Dependencies.pm'         # the POD is already auto-generated
  61    ],
  62    # these appear everywhere, and are typically lower-level methods not used by the general user
  63    skip_inherits     => [ qw/
  64       DBIx::Class
  65       DBIx::Class::Componentised
  66       Class::C3::Componentised
  67       DBIx::Class::AccessorGroup
  68       Class::Accessor::Grouped
  69       Moose::Object
  70       Exporter
  71    / ],
  72    force_inherits    => {
  73       'DBIx::Class::Manual::ResultClass' => 'DBIx::Class::Core',  # this forces the contents of ::Core to be dumped into the POD doc for ::ResultClass
  74    },
  75    dead_links        => '',
  76    method_format     => 'L<%m|%c/%m>',
  77    #debug => 1,
  78 })->write_pod;
  79
  80 # important - write_pod returns undef >.<
  81 1;