From 40ee28bac9e9524eeaaa52f48cc24c950b918d1e Mon Sep 17 00:00:00 2001 From: "mkanat%bugzilla.org" <> Date: Wed, 6 Sep 2006 02:00:55 +0000 Subject: Bug 350613: Bugzilla should ship with built perldoc Patch By Max Kanat-Alexander r=colin, a=myk --- Bugzilla/Install/Filesystem.pm | 8 ++- docs/.cvsignore | 1 - docs/html/.cvsignore | 1 + docs/html/api/.cvsignore | 3 + docs/html/api/style.css | 107 ++++++++++++++++++++++++++++++ docs/lib/Pod/Simple/HTML/Bugzilla.pm | 78 ++++++++++++++++++++++ docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm | 107 ++++++++++++++++++++++++++++++ docs/makedocs.pl | 70 ++++++++++++++++--- docs/xml/.cvsignore | 1 + 9 files changed, 362 insertions(+), 14 deletions(-) create mode 100644 docs/html/.cvsignore create mode 100644 docs/html/api/.cvsignore create mode 100644 docs/html/api/style.css create mode 100644 docs/lib/Pod/Simple/HTML/Bugzilla.pm create mode 100644 docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm create mode 100644 docs/xml/.cvsignore 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 + */ + +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 + +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 => ''; +use constant DOCTYPE => ''; + +sub new { + my $self = shift->SUPER::new(@_); + + my $doctype = $self->DOCTYPE; + my $content_type = $self->META_CT; + + my $html_pre_title = < + + +END_HTML + + my $html_post_title = <<END_HTML; + + $content_type + + +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
";
+    $self->{'Tagmap'}->{'VerbatimFormatted'} = "\n
";
+    $self->{'Tagmap'}->{'F'} = "";
+    $self->{'Tagmap'}->{'C'} = "";
+
+    # 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'}} "
" . $self->get_short_title . "
";
+    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 
+
+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[
%s
\n
\n],
+                esc($category), esc($category);
+        print $Contents '' . "\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
+      
+            print $Contents $html;
+        }
+        print $Contents "
$name$description
\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 
 #                 Jacob Steenhagen 
 #                 Colin Ogilvie 
+#                 Max Kanat-Alexander 
 
 # 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 = <
+  
+    $content_type
+    Bugzilla $bz_version API Documentation
+  
+  
+    
Bugzilla $bz_version API Documentation

+END_HTML
+
+    $converter->contents_page_start($contents_start);
+    $converter->contents_page_end("");
+    $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
-- 
cgit v1.2.3-24-g4f1b