зеркало из https://github.com/mozilla/pjs.git
Bug 350613: Bugzilla should ship with built perldoc
Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=colin, a=myk
This commit is contained in:
mkanat%bugzilla.org
Родитель
86157bd887
Коммит
6fc3d28242
|
|
@ -107,7 +107,7 @@ sub FILESYSTEM {
|
||||||
'whine.pl' => { perms => $ws_executable },
|
'whine.pl' => { perms => $ws_executable },
|
||||||
'customfield.pl' => { perms => $owner_executable },
|
'customfield.pl' => { perms => $owner_executable },
|
||||||
|
|
||||||
'docs/html/makedocs.pl' => { perms => $owner_executable },
|
'docs/makedocs.pl' => { perms => $owner_executable },
|
||||||
'docs/rel_notes.txt' => { perms => $ws_readable },
|
'docs/rel_notes.txt' => { perms => $ws_readable },
|
||||||
'docs/README.docs' => { perms => $owner_readable },
|
'docs/README.docs' => { perms => $owner_readable },
|
||||||
"$datadir/bugzilla-update.xml" => { perms => $ws_writeable },
|
"$datadir/bugzilla-update.xml" => { perms => $ws_writeable },
|
||||||
|
|
@ -164,6 +164,8 @@ sub FILESYSTEM {
|
||||||
dirs => $ws_dir_readable },
|
dirs => $ws_dir_readable },
|
||||||
'docs/images' => { files => $ws_readable,
|
'docs/images' => { files => $ws_readable,
|
||||||
dirs => $ws_dir_readable },
|
dirs => $ws_dir_readable },
|
||||||
|
'docs/lib' => { files => $owner_readable,
|
||||||
|
dirs => $owner_dir_readable },
|
||||||
'docs/xml' => { files => $owner_readable,
|
'docs/xml' => { files => $owner_readable,
|
||||||
dirs => $owner_dir_readable },
|
dirs => $owner_dir_readable },
|
||||||
);
|
);
|
||||||
|
|
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
txt
|
|
||||||
html
|
|
||||||
pdf
|
|
||||||
|
|
@ -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;
|
||||||
|
|
@ -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;
|
||||||
|
|
@ -21,17 +21,35 @@
|
||||||
# Contributor(s): Matthew Tuck <matty@chariot.net.au>
|
# Contributor(s): Matthew Tuck <matty@chariot.net.au>
|
||||||
# Jacob Steenhagen <jake@bugzilla.org>
|
# Jacob Steenhagen <jake@bugzilla.org>
|
||||||
# Colin Ogilvie <colin.ogilvie@gmail.com>
|
# Colin Ogilvie <colin.ogilvie@gmail.com>
|
||||||
|
# Max Kanat-Alexander <mkanat@bugzilla.org>
|
||||||
|
|
||||||
# This script compiles all the documentation.
|
# This script compiles all the documentation.
|
||||||
|
|
||||||
use diagnostics;
|
|
||||||
use strict;
|
use strict;
|
||||||
|
|
||||||
use File::Basename;
|
# We need to be in this directory to use our libraries.
|
||||||
use lib("..");
|
BEGIN {
|
||||||
use Bugzilla::Install::Requirements qw (REQUIRED_MODULES OPTIONAL_MODULES MOD_PERL_MODULES);
|
require File::Basename;
|
||||||
use Bugzilla::Constants qw (DB_MODULE);
|
import File::Basename qw(dirname);
|
||||||
chdir dirname($0);
|
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
|
# 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 ...
|
# Make the docs ...
|
||||||
###############################################################################
|
###############################################################################
|
||||||
|
|
||||||
if (!-d 'html') {
|
|
||||||
unlink 'html';
|
|
||||||
mkdir 'html', 0755;
|
|
||||||
}
|
|
||||||
if (!-d 'txt') {
|
if (!-d 'txt') {
|
||||||
unlink 'txt';
|
unlink 'txt';
|
||||||
mkdir 'txt', 0755;
|
mkdir 'txt', 0755;
|
||||||
|
|
@ -133,6 +181,8 @@ if (!-d 'pdf') {
|
||||||
mkdir 'pdf', 0755;
|
mkdir 'pdf', 0755;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
make_pod() if $pod_simple;
|
||||||
|
|
||||||
chdir 'html';
|
chdir 'html';
|
||||||
|
|
||||||
MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
|
MakeDocs('separate HTML', "jade -t sgml -i html -d $LDP_HOME/ldp.dsl\#html " .
|
||||||
|
|
|
||||||
Загрузка…
Ссылка в новой задаче