diff options
| -rw-r--r-- | Bugzilla/Install/Filesystem.pm | 8 | ||||
| -rw-r--r-- | docs/.cvsignore | 1 | ||||
| -rw-r--r-- | docs/html/.cvsignore | 1 | ||||
| -rw-r--r-- | docs/html/api/.cvsignore | 3 | ||||
| -rw-r--r-- | docs/html/api/style.css | 107 | ||||
| -rw-r--r-- | docs/lib/Pod/Simple/HTML/Bugzilla.pm | 78 | ||||
| -rw-r--r-- | docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm | 107 | ||||
| -rw-r--r-- | docs/makedocs.pl | 70 | ||||
| -rw-r--r-- | docs/xml/.cvsignore | 1 |
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 |