summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormkanat%bugzilla.org <>2006-09-06 04:00:55 +0200
committermkanat%bugzilla.org <>2006-09-06 04:00:55 +0200
commit40ee28bac9e9524eeaaa52f48cc24c950b918d1e (patch)
treedf221ccb31151c7a8df9bf5701140297082acefc
parent971d73458f19eb7d1a3600ee7bfd11b16cbc698a (diff)
downloadbugzilla-40ee28bac9e9524eeaaa52f48cc24c950b918d1e.tar.gz
bugzilla-40ee28bac9e9524eeaaa52f48cc24c950b918d1e.tar.xz
Bug 350613: Bugzilla should ship with built perldoc
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=colin, a=myk
-rw-r--r--Bugzilla/Install/Filesystem.pm8
-rw-r--r--docs/.cvsignore1
-rw-r--r--docs/html/.cvsignore1
-rw-r--r--docs/html/api/.cvsignore3
-rw-r--r--docs/html/api/style.css107
-rw-r--r--docs/lib/Pod/Simple/HTML/Bugzilla.pm78
-rw-r--r--docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm107
-rw-r--r--docs/makedocs.pl70
-rw-r--r--docs/xml/.cvsignore1
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