summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/lib/Pod/Simple/HTML/Bugzilla.pm48
-rw-r--r--docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm120
-rwxr-xr-xdocs/makedocs.pl136
3 files changed, 154 insertions, 150 deletions
diff --git a/docs/lib/Pod/Simple/HTML/Bugzilla.pm b/docs/lib/Pod/Simple/HTML/Bugzilla.pm
index ffbd0775c..5a2203473 100644
--- a/docs/lib/Pod/Simple/HTML/Bugzilla.pm
+++ b/docs/lib/Pod/Simple/HTML/Bugzilla.pm
@@ -16,53 +16,53 @@ use parent 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">';
+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 $self = shift->SUPER::new(@_);
- my $doctype = $self->DOCTYPE;
- my $content_type = $self->META_CT;
+ my $doctype = $self->DOCTYPE;
+ my $content_type = $self->META_CT;
- my $html_pre_title = <<END_HTML;
+ my $html_pre_title = <<END_HTML;
$doctype
<html>
<head>
<title>
END_HTML
- my $html_post_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);
+ $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>";
+ # 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'};
+ # Don't put head4 tags into the Table of Contents. We have this
+ delete $Pod::Simple::HTML::ToIndex{'head4'};
- return $self;
+ 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;
+ 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
index c9e28eab2..ae05ecf87 100644
--- a/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm
+++ b/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm
@@ -21,90 +21,92 @@ BEGIN { *esc = \&Pod::Simple::HTML::esc }
# 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', 'email_in',
- 'install-module', 'sanitycheck', 'jobqueue', 'migrate',
- 'collectstats'],
- Modules => ['bugzilla'],
- Extensions => ['extensions'],
+ Files => [
+ 'importxml', 'contrib', 'checksetup', 'email_in',
+ 'install-module', 'sanitycheck', 'jobqueue', 'migrate',
+ 'collectstats'
+ ],
+ 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} || '';
- $description = esc($description);
- my $html = <<END_HTML;
+ 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} || '';
+ $description = esc($description);
+ 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";
+ print $Contents $html;
}
+ print $Contents "</table></dd>\n\n";
+ }
- return 1;
+ 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 $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;
+ 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;
+ $self->{bugzilla_desc} ||= {};
+ $self->{bugzilla_desc}->{join('::', @$namelets)} = $description;
- return $retval;
+ return $retval;
}
# Exclude modules being in lib/.
sub find_all_pods {
- my($self, $dirs) = @_;
- my $mod2path = $self->SUPER::find_all_pods($dirs);
- foreach my $mod (keys %$mod2path) {
- delete $mod2path->{$mod} if $mod =~ /^lib::/;
- }
- return $mod2path;
+ my ($self, $dirs) = @_;
+ my $mod2path = $self->SUPER::find_all_pods($dirs);
+ foreach my $mod (keys %$mod2path) {
+ delete $mod2path->{$mod} if $mod =~ /^lib::/;
+ }
+ return $mod2path;
}
1;
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index 73bd6ce86..feec5f0f5 100755
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -48,29 +48,30 @@ use Pod::Simple::HTML::Bugzilla;
###############################################################################
my $error_found = 0;
+
sub MakeDocs {
- my ($name, $cmdline) = @_;
+ my ($name, $cmdline) = @_;
- say "Creating $name documentation ..." if defined $name;
- say "make $cmdline\n";
- system('make', $cmdline) == 0
- or $error_found = 1;
- print "\n";
+ say "Creating $name documentation ..." if defined $name;
+ say "make $cmdline\n";
+ system('make', $cmdline) == 0 or $error_found = 1;
+ print "\n";
}
sub make_pod {
- say "Creating API documentation...";
+ say "Creating API documentation...";
+
+ my $converter = Pod::Simple::HTMLBatch::Bugzilla->new;
- my $converter = Pod::Simple::HTMLBatch::Bugzilla->new;
- # Don't output progress information.
- $converter->verbose(0);
- $converter->html_render_class('Pod::Simple::HTML::Bugzilla');
+ # 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 $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;
+ my $contents_start = <<END_HTML;
$doctype
<html>
<head>
@@ -81,16 +82,16 @@ $doctype
<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);
- mkdir("html");
- mkdir("html/api");
- $converter->batch_convert(['../../'], 'html/api/');
+ $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);
+ mkdir("html");
+ mkdir("html/api");
+ $converter->batch_convert(['../../'], 'html/api/');
- print "\n";
+ print "\n";
}
###############################################################################
@@ -98,67 +99,68 @@ END_HTML
###############################################################################
my @langs;
+
# search for sub directories which have a 'rst' sub-directory
opendir(LANGS, './');
foreach my $dir (readdir(LANGS)) {
- next if (($dir eq '.') || ($dir eq '..') || (! -d $dir));
- if (-d "$dir/rst") {
- push(@langs, $dir);
- }
+ next if (($dir eq '.') || ($dir eq '..') || (!-d $dir));
+ if (-d "$dir/rst") {
+ push(@langs, $dir);
+ }
}
closedir(LANGS);
my $docparent = getcwd();
foreach my $lang (@langs) {
- chdir "$docparent/$lang";
+ chdir "$docparent/$lang";
- make_pod();
+ make_pod();
- next if grep { $_ eq '--pod-only' } @ARGV;
+ next if grep { $_ eq '--pod-only' } @ARGV;
- chdir $docparent;
+ chdir $docparent;
- # Generate extension documentation, both normal and API
- my $ext_dir = bz_locations()->{'extensionsdir'};
- my @ext_paths = grep { $_ !~ /\/create\.pl$/ && ! -e "$_/disabled" }
- glob("$ext_dir/*");
- my %extensions;
- foreach my $item (@ext_paths) {
- my $basename = basename($item);
- if (-d "$item/docs/$lang/rst") {
- $extensions{$basename} = "$item/docs/$lang/rst";
- }
+ # Generate extension documentation, both normal and API
+ my $ext_dir = bz_locations()->{'extensionsdir'};
+ my @ext_paths
+ = grep { $_ !~ /\/create\.pl$/ && !-e "$_/disabled" } glob("$ext_dir/*");
+ my %extensions;
+ foreach my $item (@ext_paths) {
+ my $basename = basename($item);
+ if (-d "$item/docs/$lang/rst") {
+ $extensions{$basename} = "$item/docs/$lang/rst";
}
+ }
- # Collect up local extension documentation into the extensions/ dir.
- rmtree("$lang/rst/extensions", 0, 1);
+ # Collect up local extension documentation into the extensions/ dir.
+ rmtree("$lang/rst/extensions", 0, 1);
- foreach my $ext_name (keys %extensions) {
- my $src = $extensions{$ext_name} . "/*";
- my $dst = "$docparent/$lang/rst/extensions/$ext_name";
- mkdir($dst) unless -d $dst;
- rcopy($src, $dst);
- }
+ foreach my $ext_name (keys %extensions) {
+ my $src = $extensions{$ext_name} . "/*";
+ my $dst = "$docparent/$lang/rst/extensions/$ext_name";
+ mkdir($dst) unless -d $dst;
+ rcopy($src, $dst);
+ }
- chdir "$docparent/$lang";
-
- MakeDocs('HTML', 'html');
- MakeDocs('TXT', 'text');
-
- if (grep { $_ eq '--with-pdf' } @ARGV) {
- if (which('pdflatex')) {
- MakeDocs('PDF', 'latexpdf');
- }
- elsif (which('rst2pdf')) {
- rmtree('pdf', 0, 1);
- MakeDocs('PDF', 'pdf');
- }
- else {
- say 'pdflatex or rst2pdf not found. Skipping PDF file creation';
- }
+ chdir "$docparent/$lang";
+
+ MakeDocs('HTML', 'html');
+ MakeDocs('TXT', 'text');
+
+ if (grep { $_ eq '--with-pdf' } @ARGV) {
+ if (which('pdflatex')) {
+ MakeDocs('PDF', 'latexpdf');
+ }
+ elsif (which('rst2pdf')) {
+ rmtree('pdf', 0, 1);
+ MakeDocs('PDF', 'pdf');
+ }
+ else {
+ say 'pdflatex or rst2pdf not found. Skipping PDF file creation';
}
+ }
- rmtree('doctrees', 0, 1);
+ rmtree('doctrees', 0, 1);
}
die "Error occurred building the documentation\n" if $error_found;
generated by cgit v1.2.3-24-g4f1b (git 2.32.0) at 2024-05-17 22:18:17 +0200