Permalink
Browse files

Added documentation

  • Loading branch information...
Getty committed Dec 31, 2012
1 parent 1702bcd commit 241b7058c91d4c08523603ac1e8fa51d7512c1d8
Showing with 312 additions and 3 deletions.
  1. +9 −0 bin/ddg_publisher
  2. +41 −0 lib/DDG/App/Publisher.pm
  3. +53 −0 lib/DDG/Publisher.pm
  4. +56 −0 lib/DDG/Publisher/DirRole.pm
  5. +88 −1 lib/DDG/Publisher/File.pm
  6. +65 −2 lib/DDG/Publisher/SiteRole.pm
View
9 bin/ddg_publisher 100755 → 100644
@@ -2,6 +2,15 @@
# PODNAME: ddg_publisher
# ABSTRACT: Generating static parts of DuckDuckGo
+=head1 SYNOPSIS
+
+ perl -Ilib bin/ddg_publisher ~/test_publish
+
+ # compressing html to one line without comments and unnecessary whitespaces
+ perl -Ilib bin/ddg_publisher --no_compression ~/test_publish
+
+=cut
+
use FindBin qw($Bin);
use lib "$Bin/../lib";
View
@@ -1,29 +1,70 @@
package DDG::App::Publisher;
+# ABSTRACT: The application class
+
+=head1 SYNOPSIS
+
+=cut
use MooX;
use MooX::Options protect_argv => 0;
use Path::Class;
use DDG::Publisher;
+=attr no_compression
+
+If this is deactivated the compression will not used, which speeds up the
+things for development.
+
+=cut
+
option no_compression => (
is => 'ro',
predicate => 1,
);
+=attr dryrun
+
+If this option is activated the publisher will not generate any files and
+will just execute the code so that tokens and generatly sanity of the code
+can be checked. This option requires a filename to be given, so this is used
+for the dryrun of L<Locale::Simple>.
+
+=cut
+
option dryrun => (
format => 's',
is => 'ro',
predicate => 1,
);
+=attr site_only
+
+Use this option to only execute one specific file. You can use it several
+times. Give the classname of the site you want to execute with the
+B<DDG::Publisher::Site::> part. This option can be given several times.
+
+=cut
+
option site_only => (
format => 's',
is => 'ro',
predicate => 1,
);
+=method run
+
+This method gets executed for the run of the publisher
+
+=cut
+
sub run {
my ( $self ) = @_;
+
+ #
+ # Getting the target directory from $ENV{DDG_PUBLISHER_TARGETDIR}
+ # or from command line.
+ #
+
my $target = @ARGV
? shift @ARGV
: defined $ENV{DDG_PUBLISHER_TARGETDIR}
View
@@ -9,6 +9,12 @@ use HTML::Packer;
use String::ProgressBar;
use JSON;
+=attr site_classes
+
+List of classes that should get executed on publishing.
+
+=cut
+
has site_classes => (
is => 'ro',
lazy => 1,
@@ -21,17 +27,35 @@ sub _build_site_classes {[qw(
Dontbubbleus
)]}
+=attr sites
+
+This attribute holds the objects of the site classes that should get build.
+
+=cut
+
has sites => (
is => 'ro',
lazy => 1,
builder => 1,
);
+=attr no_compression
+
+See L<DDG::App::Publisher/no_compression>.
+
+=cut
+
has no_compression => (
is => 'ro',
default => sub { 0 },
);
+=attr dryrun
+
+See L<DDG::App::Publisher/dryrun>.
+
+=cut
+
has dryrun => (
is => 'ro',
predicate => 1,
@@ -53,6 +77,12 @@ sub BUILD {
$self->sites;
}
+=method publish_to
+
+This method it called to publish the files to the given specific directory.
+
+=cut
+
sub publish_to {
my ( $self, $target ) = @_;
my $target_dir = dir($target)->absolute;
@@ -62,7 +92,17 @@ sub publish_to {
unless ($self->no_compression) {
$packer = HTML::Packer->init();
}
+
+ #
+ # For every site...
+ #
+
for my $site (@{$self->sites}) {
+
+ #
+ # For every dir in the site...
+ #
+
for my $dir (values %{$site->dirs}) {
print "\n".(ref $site).$dir->web_path."\n\n";
my @files = values %{$dir->fullpath_files};
@@ -79,6 +119,12 @@ sub publish_to {
$real_file->dir->mkpath unless -f $real_file->dir->absolute->stringify;
my $content = $_->content;
utf8::encode($content);
+
+ #
+ # If compression is requested, then the content of the files
+ # get compressed via HTML::Packer here.
+ #
+
if ($packer) {
$packer->minify(\$content,{
remove_comments => 0,
@@ -94,6 +140,13 @@ sub publish_to {
}
print "\n";
}
+
+ #
+ # Generate a datafile for the site, which can be used for deeper
+ # processing of the static files. (It's used by the internal code
+ # of DDG to generate, for example, the nginx config)
+ #
+
my $data_file = file($target_dir,$site->key.'.json')->absolute;
io($data_file)->print(encode_json($site->save_data));
};
@@ -1,4 +1,5 @@
package DDG::Publisher::DirRole;
+# ABSTRACT: The role for a directory in the publisher system
use MooX::Role;
use DDG::Publisher::File;
@@ -8,16 +9,34 @@ requires qw(
pages
);
+=attr key
+
+The key inside the site for this directory. Required for instantiation.
+
+=cut
+
has key => (
is => 'ro',
required => 1,
);
+=attr site
+
+Site object for this directory. Required for instantiation.
+
+=cut
+
has site => (
is => 'ro',
required => 1,
);
+=attr files
+
+Contains a hash of the files for this directory.
+
+=cut
+
has files => (
is => 'ro',
lazy => 1,
@@ -57,6 +76,13 @@ sub _build_files {
return \%files;
}
+=attr fullpath
+
+This hash also contains all files, but with the full path on the filesystem
+as key, so that collides can be detected.
+
+=cut
+
has fullpath_files => (
is => 'ro',
lazy => 1,
@@ -80,6 +106,14 @@ sub _build_fullpath_files {
return \%fullpath_files;
}
+=attr pages_coderefs
+
+This attribute contains all the coderefs for the pages that have to be
+generated for this specific directory. It uses L<pages> as builder. Normally
+you override L<pages> in your site class.
+
+=cut
+
has pages_coderefs => (
is => 'ro',
lazy => 1,
@@ -88,6 +122,15 @@ has pages_coderefs => (
sub pages {{}}
+=attr statics_coderefs
+
+This attribute contains all the coderefs for the static pages that have to be
+generated for this specific directory. It uses L<statics> as builder. Normally
+you override L<statics> in your site class. A static file is not generated for
+every language
+
+=cut
+
has statics_coderefs => (
is => 'ro',
lazy => 1,
@@ -96,6 +139,12 @@ has statics_coderefs => (
sub statics {{}}
+=attr web_path
+
+The path on the web for this directory.
+
+=cut
+
has web_path => (
is => 'ro',
lazy => 1,
@@ -104,6 +153,13 @@ has web_path => (
sub _build_web_path { my @path = shift->path; defined $path[1] ? $path[1] : $path[0] }
+=attr template_path
+
+This is the path inside the templates, used for the pages and statics of this
+directory.
+
+=cut
+
has template_path => (
is => 'ro',
lazy => 1,
Oops, something went wrong.

0 comments on commit 241b705

Please sign in to comment.