Bug 350613: Bugzilla should ship with built perldoc

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=colin, a=myk

9 files changed, 362 insertions, 14 deletions

diff --git a/Bugzilla/Install/Filesystem.pm b/Bugzilla/Install/Filesystem.pm
index 02131531c..5261989dd 100644
--- a/Bugzilla/Install/Filesystem.pm
+++ b/Bugzilla/Install/Filesystem.pm
@@ -107,9 +107,9 @@ sub FILESYSTEM {
         'whine.pl'        => { perms => $ws_executable },
         'customfield.pl'  => { perms => $owner_executable },
 
-        'docs/html/makedocs.pl' => { perms => $owner_executable },
-        'docs/rel_notes.txt'    => { perms => $ws_readable },
-        'docs/README.docs'      => { perms => $owner_readable },
+        'docs/makedocs.pl'   => { perms => $owner_executable },
+        'docs/rel_notes.txt' => { perms => $ws_readable },
+        'docs/README.docs'   => { perms => $owner_readable },
         "$datadir/bugzilla-update.xml" => { perms => $ws_writeable },
         "$datadir/params" => { perms => $ws_writeable },
     );
@@ -164,6 +164,8 @@ sub FILESYSTEM {
                                      dirs => $ws_dir_readable },
          'docs/images'         => { files => $ws_readable,
                                      dirs => $ws_dir_readable },
+         'docs/lib'            => { files => $owner_readable,
+                                     dirs => $owner_dir_readable },
          'docs/xml'            => { files => $owner_readable,
                                      dirs => $owner_dir_readable },
     );
diff --git a/docs/.cvsignore b/docs/.cvsignore
index e5004814b..8453d5c46 100644
--- a/docs/.cvsignore
+++ b/docs/.cvsignore
@@ -1,3 +1,2 @@
 txt
-html
 pdf
diff --git a/docs/html/.cvsignore b/docs/html/.cvsignore
new file mode 100644
index 000000000..2d19fc766
--- /dev/null
+++ b/docs/html/.cvsignore
@@ -0,0 +1 @@
+*.html
diff --git a/docs/html/api/.cvsignore b/docs/html/api/.cvsignore
new file mode 100644
index 000000000..10d63bfdf
--- /dev/null
+++ b/docs/html/api/.cvsignore
@@ -0,0 +1,3 @@
+*.html
+Bugzilla
+contrib
diff --git a/docs/html/api/style.css b/docs/html/api/style.css
new file mode 100644
index 000000000..1c9a6bcb1
--- /dev/null
+++ b/docs/html/api/style.css
@@ -0,0 +1,107 @@
+/* The contents of this file are subject to the Mozilla Public
+ * License Version 1.1 (the "License"); you may not use this file
+ * except in compliance with the License. You may obtain a copy of
+ * the License at http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS
+ * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+ * implied. See the License for the specific language governing
+ * rights and limitations under the License.
+ *
+ * The Original Code is the Bugzilla Bug Tracking System.
+ *
+ * The Initial Developer of the Original Code is Everything Solved.
+ * Portions created by Everything Solved are Copyright (C) 2006 
+ * Everything Solved. All Rights Reserved.
+ *
+ * Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+ */
+
+body {
+  background: white;
+  color: #111;
+  padding: 0 1em;
+  margin: 0;
+  font-family: Verdana, Arial, sans-serif;
+  font-size: small;
+}
+
+a:link, a:active { color: #36415c; }
+a:visited { color: #666; }
+a:hover   { color: #888; }
+
+h1 {
+  font-size: 150%;
+  font-weight: bold;
+  border-bottom: 2px solid #ccc;
+}
+h2 {
+  font-size: 125%;
+  font-weight: bold;
+  border-bottom: 1px solid #ccc;
+  margin-bottom: 8px;
+}
+h3 {
+  font-size: 115%;
+  font-weight: bold;
+  margin-bottom: 0;
+  padding-bottom: 0;
+}
+
+/* This makes Description/Params/Returns look nice. */
+dd   { margin-top: .2em; }
+dd p { margin-top: 0; }
+dl   { margin-bottom: 1em; }
+
+/* This makes the names of functions slightly larger, in Gecko. */
+body > dl > dt code { font-size: 1.35em; }
+
+#pod h1 a, #pod h2 a, #pod h3 a {
+  color: #36415c;
+  text-decoration: none;
+}
+
+pre, code, tt, kbd, samp {
+  /* Unfortunately, the default monospace fonts on most browsers
+     look odd with relative sizing. */
+  font-size: 12px;
+}
+
+.code {
+  background: #eed;
+  border: 1px solid #ccc;
+}
+
+pre.code {
+  margin-left: 10px;
+  width: 90%;
+  padding: 10px;
+}
+
+/* Special styles for the Contents page */
+
+.contentspage dt {
+  font-size: large;
+  font-weight: bold;
+}
+
+.pod_desc_table {
+  border-collapse: collapse;
+  table-layout: auto;
+  border: 1px solid #ccc;
+}
+
+.pod_desc_table th {
+  text-align: left;
+}
+
+.pod_desc_table td, .pod_desc_table th {
+  padding: .25em;
+  border-top: 1px solid #ccc;
+}
+
+.pod_desc_table .odd th, .pod_desc_table .odd td {
+  background-color: #eee;
+}
+
+.pod_desc_table 
diff --git a/docs/lib/Pod/Simple/HTML/Bugzilla.pm b/docs/lib/Pod/Simple/HTML/Bugzilla.pm
new file mode 100644
index 000000000..f82ab9266
--- /dev/null
+++ b/docs/lib/Pod/Simple/HTML/Bugzilla.pm
@@ -0,0 +1,78 @@
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# The Initial Developer of the Original Code is Everything Solved.
+# Portions created by Everything Solved are Copyright (C) 2006
+# Everything Solved. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Pod::Simple::HTML::Bugzilla;
+
+use strict;
+use base qw(Pod::Simple::HTML);
+
+# Without this constant, HTMLBatch will throw undef warnings.
+use constant VERSION    => $Pod::Simple::HTML::VERSION;
+use constant CODE_CLASS => ' class="code"';
+use constant META_CT  => '<meta http-equiv="Content-Type" content="text/html;'
+                         . ' charset=UTF-8">';
+use constant DOCTYPE  => '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01'
+    . ' Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">';
+
+sub new {
+    my $self    = shift->SUPER::new(@_);
+
+    my $doctype      = $self->DOCTYPE;
+    my $content_type = $self->META_CT;
+
+    my $html_pre_title = <<END_HTML;
+$doctype
+<html>
+  <head>
+    <title>
+END_HTML
+
+    my $html_post_title = <<END_HTML;
+</title>
+    $content_type
+  </head>
+  <body id="pod">
+END_HTML
+
+    $self->html_header_before_title($html_pre_title);
+    $self->html_header_after_title($html_post_title);
+
+    # Fix some tags to have classes so that we can adjust them.
+    my $code = CODE_CLASS;
+    $self->{'Tagmap'}->{'Verbatim'} = "\n<pre $code>";
+    $self->{'Tagmap'}->{'VerbatimFormatted'} = "\n<pre $code>";
+    $self->{'Tagmap'}->{'F'} = "<em $code>";
+    $self->{'Tagmap'}->{'C'} = "<code $code>";
+
+    # Don't put head4 tags into the Table of Contents. We have this
+    delete $Pod::Simple::HTML::ToIndex{'head4'};
+
+    return $self;
+}
+
+# Override do_beginning to put the name of the module at the top
+sub do_beginning {
+    my $self = shift;
+    $self->SUPER::do_beginning(@_);
+    print {$self->{'output_fh'}} "<h1>" . $self->get_short_title . "</h1>";
+    return 1;
+}
+
+1;
diff --git a/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm b/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm
new file mode 100644
index 000000000..37369f142
--- /dev/null
+++ b/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm
@@ -0,0 +1,107 @@
+# -*- Mode: perl; indent-tabs-mode: nil -*- 
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the "License"); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS
+# IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# The Initial Developer of the Original Code is Everything Solved.
+# Portions created by Everything Solved are Copyright (C) 2006
+# Everything Solved. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Pod::Simple::HTMLBatch::Bugzilla;
+
+use strict;
+use base qw(Pod::Simple::HTMLBatch);
+
+# This is the same hack that HTMLBatch does to "import" this subroutine.
+BEGIN { *esc = \&Pod::Simple::HTML::esc }
+
+# Describes how top-level modules should be sorted and named. This
+# is a translation from HTMLBatch's names to our categories.
+# Note that if you leave out a category here, it will not be indexed
+# in the contents file, even though its HTML POD will still exist.
+use constant FILE_TRANSLATION => {
+    Files      => ['importxml', 'contrib', 'checksetup'],
+    Modules    => ['bugzilla'],
+    Extensions => ['extensions'],
+};
+
+# This is basically copied from Pod::Simple::HTMLBatch, and overridden
+# so that we can format things more nicely.
+sub _write_contents_middle {
+    my ($self, $Contents, $outfile, $toplevel2submodules) = @_;
+
+    my $file_trans = FILE_TRANSLATION;
+
+    # For every top-level category...
+    foreach my $category (sort keys %$file_trans) {
+        # Get all of the HTMLBatch categories that should be in this
+        # category.
+        my @category_data;
+        foreach my $b_category (@{$file_trans->{$category}}) {
+            my $data = $toplevel2submodules->{$b_category};
+            push(@category_data, @$data) if $data;
+        }
+        next unless @category_data;
+
+        my @downlines = sort {$a->[-1] cmp $b->[-1]} @category_data;
+
+        # And finally, actually print out the table for this category. 
+        printf $Contents qq[<dt><a name="%s">%s</a></dt>\n<dd>\n],
+                esc($category), esc($category);
+        print $Contents '<table class="pod_desc_table">' . "\n";
+
+        # For every POD...
+        my $row_count = 0;
+        foreach my $e (@downlines) {
+            $row_count++;
+            my $even_or_odd = $row_count % 2 ? 'even' : 'odd';
+            my $name = esc($e->[0]);
+            my $path = join( "/", '.', esc(@{$e->[3]}) )
+               . $Pod::Simple::HTML::HTML_EXTENSION;
+            my $description = $self->{bugzilla_desc}->{$name} || '';
+            my $html = <<END_HTML;
+<tr class="$even_or_odd">
+  <th><a href="$path">$name</a></th>
+  <td>$description</td>
+</tr>
+END_HTML
+      
+            print $Contents $html;
+        }
+        print $Contents "</table></dd>\n\n";
+    }
+
+    return 1;
+}
+
+# This stores the name and description for each file, so that
+# we can get that information out later.
+sub note_for_contents_file {
+    my $self = shift;
+    my $retval = $self->SUPER::note_for_contents_file(@_);
+
+    my ($namelets, $infile) = @_;
+    my $parser   = $self->html_render_class->new;
+    $parser->set_source($infile);
+    my $full_title = $parser->get_title;
+    $full_title =~ /^\S+\s+-+\s+(.+)/;
+    my $description = $1;
+    
+    $self->{bugzilla_desc} ||= {};
+    $self->{bugzilla_desc}->{join('::', @$namelets)} = $description;
+
+    return $retval;
+}
+
+1;
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index 1b83e5d7a..f74f87cc3 100644
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -21,17 +21,35 @@
 # Contributor(s): Matthew Tuck <matty@chariot.net.au>
 #                 Jacob Steenhagen <jake@bugzilla.org>
 #                 Colin Ogilvie <colin.ogilvie@gmail.com>
+#                 Max Kanat-Alexander <mkanat@bugzilla.org>
 
 # This script compiles all the documentation.
 
-use diagnostics;
 use strict;
 
-use File::Basename;
-use lib("..");
-use Bugzilla::Install::Requirements qw (REQUIRED_MODULES OPTIONAL_MODULES MOD_PERL_MODULES);
-use Bugzilla::Constants qw (DB_MODULE);
-chdir dirname($0);
+# We need to be in this directory to use our libraries.
+BEGIN {
+    require File::Basename;
+    import File::Basename qw(dirname);
+    chdir dirname($0);
+}
+
+use lib qw(.. lib);
+
+# We only compile our POD if Pod::Simple is installed. We do the checks
+# this way so that if there's a compile error in Pod::Simple::HTML::Bugzilla,
+# makedocs doesn't just silently fail, but instead actually tells us there's
+# a compile error.
+my $pod_simple;
+if (eval { require Pod::Simple }) {
+    require Pod::Simple::HTMLBatch::Bugzilla;
+    require Pod::Simple::HTML::Bugzilla;
+    $pod_simple = 1;
+};
+
+use Bugzilla::Install::Requirements 
+    qw(REQUIRED_MODULES OPTIONAL_MODULES MOD_PERL_MODULES);
+use Bugzilla::Constants qw(DB_MODULE BUGZILLA_VERSION);
 
 ###############################################################################
 # Generate minimum version list
@@ -116,14 +134,44 @@ sub MakeDocs {
 
 }
 
+sub make_pod {
+
+    print "Creating API documentation...\n";
+
+    my $converter = Pod::Simple::HTMLBatch::Bugzilla->new;
+    # Don't output progress information.
+    $converter->verbose(0);
+    $converter->html_render_class('Pod::Simple::HTML::Bugzilla');
+
+    my $doctype      = Pod::Simple::HTML::Bugzilla->DOCTYPE;
+    my $content_type = Pod::Simple::HTML::Bugzilla->META_CT;
+    my $bz_version   = BUGZILLA_VERSION;
+
+    my $contents_start = <<END_HTML;
+$doctype
+<html>
+  <head>
+    $content_type
+    <title>Bugzilla $bz_version API Documentation</title>
+  </head>
+  <body class="contentspage">
+    <h1>Bugzilla $bz_version API Documentation</h1>
+END_HTML
+
+    $converter->contents_page_start($contents_start);
+    $converter->contents_page_end("</body></html>");
+    $converter->add_css('style.css');
+    $converter->javascript_flurry(0);
+    $converter->css_flurry(0);
+    $converter->batch_convert(['../'], 'html/api/');
+
+    print "\n";
+}
+
 ###############################################################################
 # Make the docs ...
 ###############################################################################
 
-if (!-d 'html') {
-    unlink 'html';
-    mkdir 'html', 0755;
-}
 if (!-d 'txt') {
     unlink 'txt';
     mkdir 'txt', 0755;
@@ -133,6 +181,8 @@ if (!-d 'pdf') {
     mkdir 'pdf', 0755;
 }
 
+make_pod() if $pod_simple;
+
 chdir 'html';
 
 MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
diff --git a/docs/xml/.cvsignore b/docs/xml/.cvsignore
new file mode 100644
index 000000000..ef6b304bc
--- /dev/null
+++ b/docs/xml/.cvsignore
@@ -0,0 +1 @@
+bugzilla.ent