BEGIN { chdir dirname($0); }
use lib qw(.. ../lib lib ../local/lib/perl5);
+use open ':encoding(utf8)';
use Cwd;
use File::Copy::Recursive qw(rcopy);
use File::Path qw(rmtree make_path);
use File::Which qw(which);
use Pod::Simple;
+use Pod::ParseLink;
use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations);
-use Pod::Simple::HTMLBatch::Bugzilla;
-use Pod::Simple::HTML::Bugzilla;
+use Pod::Simple::Search;
+use Pod::POM::View::Restructured;
+use Tie::File;
+use File::Spec::Functions qw(:ALL);
###############################################################################
# Subs
###############################################################################
my $error_found = 0;
+
sub MakeDocs {
my ($name, $cmdline) = @_;
print "\n";
}
-sub make_pod {
- say "Creating API documentation...";
-
- 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);
- make_path('html/integrating/api');
- $converter->batch_convert(['../../'], 'html/integrating/api');
+# Compile all the POD and make it part of the API docs
+# Also duplicate some Extension docs into the User section, Admin section, and
+# WebService docs
+sub pod2rst {
+ my $path = shift;
- print "\n";
+ say "Converting POD to RST...";
+ my $name2path = Pod::Simple::Search->new->inc(0)->verbose(0)
+ ->survey(@{ ['../'] });
+
+ my $ind_path = catdir($path, 'rst', 'integrating', 'internals');
+ rmtree($ind_path);
+ make_path($ind_path);
+
+ my $FILE;
+ open($FILE, '>', catfile($ind_path, 'index.rst'))
+ || die("Can't open rst file");
+ print($FILE <<'EOI');
+.. highlight:: perl
+
+.. _developer
+
+===================================
+Developer Documentation
+===================================
+
+This section exposes the POD for all modules and scripts, including extensions,
+in Bugzilla.
+
+.. toctree::
+ :maxdepth: 2
+
+EOI
+
+ foreach my $mod (sort keys %$name2path) {
+ # Ignoring library files;
+ if ($mod =~ /^b?(lib::|local)/) {
+ delete $name2path->{$mod};
+ next;
+ }
+
+ my $title = $mod;
+
+ my $ext = $title =~ s/^extensions:://;
+ $title =~ s/lib:://;
+ $title =~ s/::Extension$// if ($ext);
+ my $header = "=" x length($title);
+
+ my $abs_path = $name2path->{$mod};
+ my $fpath = abs2rel($abs_path, '..');
+ my ($volume, $directories, $file) = splitpath($fpath);
+ $directories =~ s/lib\///;
+ $directories = '.' if ($directories eq '');
+
+ my $dir_path = catdir($ind_path, $directories);
+ make_path($dir_path);
+ $file =~ s/\.[^.]*$//;
+ my $out_file = $file . '.rst';
+ my $full_out_file = catfile($dir_path, $out_file);
+
+ my $callbacks = {
+ link => sub {
+ my $text = shift;
+
+ my @results = parselink($text);
+
+ # A link to another page.
+ if (defined($results[1]) && defined($results[2])) {
+ if ($results[2] =~ /^http/) {
+ return ($results[2], $results[1]);
+ }
+ elsif ($results[2] =~ m/Bugzilla/) {
+ my $depth = scalar(split('/', $directories));
+ my @split = split('::', $results[2]);
+ my $base = '../' x $depth;
+ my $url = $base . join('/', @split);
+ $url .= '.html';
+ $url .= '#' . $results[3] if defined $results[3];
+ return ($url, $results[1]);
+ }
+ else {
+ # Not a Bugzilla package, link to CPAN.
+ my $url
+ = 'http://search.cpan.org/search?query='
+ . $results[2]
+ . '&mode=all';
+ return ($url, $results[1]);
+ }
+ }
+
+ # A Link within a page
+ elsif (defined($results[1]) && defined($results[4])) {
+ my $anchor = $results[1];
+ $anchor =~ s/"//g;
+ return ("#$anchor", $anchor);
+ }
+ else {
+ die "Don't know how to parse $text";
+ }
+ }
+ };
+ my $conv = Pod::POM::View::Restructured->new(
+ { namespace => $title, callbacks => $callbacks });
+ my $rv = $conv->convert_file($abs_path, $title, $full_out_file,
+ $callbacks);
+ print($FILE " ", catfile($directories, $out_file), "\n");
+
+ if ($ext) {
+ my $api_path = catdir($path, 'rst', $directories);
+ my $adminfile = catfile($api_path, "index-admin.rst");
+ my $userfile = catfile($api_path, "index-user.rst");
+ my $apifile = catfile($api_path, 'api', 'v1', 'index.rst');
+ make_path($api_path) unless -d $api_path;
+
+ # Add Core doc to User & Admin guides
+ if ($file eq 'Extension') {
+ my $FH;
+ open($FH, '<', $full_out_file) || die "$full_out_file: $!";
+ my @lines = <$FH>;
+ close $FH;
+
+ my @array;
+
+ # ensure out of order docs are at the top of the page without
+ # playing with file handles
+ tie @array, 'Tie::File', $adminfile or die "$adminfile: $!";
+ unshift @array, @lines, "", "", ".. toctree::", "", "";
+ untie @array;
+
+ tie @array, 'Tie::File', $userfile or die "$userfile: $!";
+ unshift @array, @lines, "", "", ".. toctree::", "", "";
+ untie @array;
+
+ }
+
+ # Add Config doc to Admin guide
+ elsif ($file eq 'Config') {
+ rcopy($full_out_file, $api_path);
+ `perl -E 'say " $file.rst"' >> "$adminfile"`;
+ }
+
+ # Add WebServices doc to API docs
+ elsif ($file eq 'WebService') {
+ my $apidir = catdir($api_path, 'api', 'v1');
+ make_path($apidir)
+ unless -d $apidir;
+ `perl -E 'say ".. toctree::\n\n"' >> $apifile`
+ unless -f $apifile;
+
+ my $FH;
+ open($FH, '<', $full_out_file) || die "$full_out_file: $!";
+ my @lines = <$FH>;
+ close $FH;
+
+ my @array;
+
+ tie @array, 'Tie::File', $apifile or die "$apifile: $!";
+ unshift @array, @lines;
+ untie @array;
+ }
+ elsif ($api_path =~ /WebService\/$/) {
+ my $apidir = catdir($api_path, '..', 'api', 'v1');
+ $apifile = catfile($apidir, 'index.rst');
+ make_path($apidir) unless -d $apidir;
+ rcopy($full_out_file, $apidir);
+ `perl -E 'say ".. toctree::\n\n"' >> $apifile`
+ unless -f $apifile;
+ `perl -E 'say " $file.rst"' >> $apifile`;
+ }
+ }
+ }
+
+ close($FILE);
}
###############################################################################
###############################################################################
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));
+ next if (($dir eq '.') || ($dir eq '..') || (!-d $dir));
if (-d "$dir/rst") {
push(@langs, $dir);
}
my $docparent = getcwd();
foreach my $lang (@langs) {
- chdir "$docparent/$lang";
- make_pod();
+ rmtree("$lang/html", 0, 1);
+ rmtree("$lang/txt", 0, 1);
+
+ my @sub_dirs = grep {-d} glob("$lang/rst/extensions/*");
+ rmtree(@sub_dirs, { verbose => 0, safe => 1 });
+
+ pod2rst("$docparent/$lang");
next if grep { $_ eq '--pod-only' } @ARGV;
+ chdir "$docparent/$lang";
+
MakeDocs('HTML', 'html');
- MakeDocs('TXT', 'text');
+ MakeDocs('TXT', 'text');
if (grep { $_ eq '--with-pdf' } @ARGV) {
if (which('pdflatex')) {
projects / thirdparty / bugzilla.git / commitdiff
