Skip to content

bugzilla
bugzilla
Commit bae90f4d authored by Jeff Fearn's avatar Jeff Fearn Committed by Gervase Markham
Browse files
Options

Bug 1314854: Integrate POD in to REST docs.

parent 8dae2315
Show whitespace changes
Inline Side-by-side
Showing with 208 additions and 40 deletions
Makefile.PL
View file @ bae90f4d
...@@ -168,7 +168,12 @@ my %optional_features = ( ...@@ -168,7 +168,12 @@ my %optional_features = (
prereqs => { prereqs => {
runtime => { runtime => {
requires => requires =>
{ 'File::Which' => 0, 'File::Copy::Recursive' => 0 } {
'File::Which' => 0,
'File::Copy::Recursive' => 0,
'Pod::Simple::Search' => 0,
'Pod::POM::View::Restructured' => 0,
}
} }
}, },
description => 'Documentation', description => 'Documentation',
......
docs/en/rst/conf.py
View file @ bae90f4d
...@@ -381,9 +381,9 @@ todo_include_todos = True ...@@ -381,9 +381,9 @@ todo_include_todos = True
on_rtd = os.environ.get('READTHEDOCS', None) == 'True' on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd: if on_rtd:
base_api_url = 'https://www.bugzilla.org/docs/tip/en/html/integrating/api/' base_api_url = 'https://www.bugzilla.org/docs/tip/en/html/integrating/internals/'
else: else:
base_api_url = '../integrating/api/' base_api_url = '../integrating/internals/'
extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug '), extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug '),
'api': (base_api_url + '%s', '')} 'api': (base_api_url + '%s', '')}
...@@ -399,12 +399,16 @@ ext_dir = "../../../extensions" ...@@ -399,12 +399,16 @@ ext_dir = "../../../extensions"
# Still, check just in case, so if it ever changes, we know # Still, check just in case, so if it ever changes, we know
if (os.path.isdir(ext_dir)): if (os.path.isdir(ext_dir)):
# Clear out old extensions docs # Clear out removed extensions docs
for dir in os.listdir("extensions"): for dir in os.listdir("extensions"):
# A .gitignore file is required as git doesn't like empty directories # A .gitignore file is required as git doesn't like empty directories
if dir == ".gitignore": if dir == ".gitignore":
continue continue
src = os.path.join(ext_dir, dir)
# extension dir missing, assume uninstalled
if not os.path.isdir(src):
shutil.rmtree(os.path.join("extensions", dir)) shutil.rmtree(os.path.join("extensions", dir))
# Copy in new copies # Copy in new copies
...@@ -426,6 +430,10 @@ if (os.path.isdir(ext_dir)): ...@@ -426,6 +430,10 @@ if (os.path.isdir(ext_dir)):
dst = os.path.join("extensions", ext_name) dst = os.path.join("extensions", ext_name)
# remove old docs
if (os.path.isdir(dst)):
shutil.rmtree(dst)
shutil.copytree(src, dst) shutil.copytree(src, dst)
else: else:
print "Warning: Bugzilla extension directory not found: " + ext_dir print "Warning: Bugzilla extension directory not found: " + ext_dir
docs/en/rst/integrating/index.rst
View file @ bae90f4d
...@@ -21,3 +21,4 @@ explains how to use the available mechanisms for integration and customization. ...@@ -21,3 +21,4 @@ explains how to use the available mechanisms for integration and customization.
extensions extensions
apis apis
auth-delegation auth-delegation
internals/index
docs/makedocs.pl
View file @ bae90f4d
...@@ -31,22 +31,27 @@ use File::Basename; ...@@ -31,22 +31,27 @@ use File::Basename;
BEGIN { chdir dirname($0); } BEGIN { chdir dirname($0); }
use lib qw(.. ../lib lib ../local/lib/perl5); use lib qw(.. ../lib lib ../local/lib/perl5);
use open ':encoding(utf8)';
use Cwd; use Cwd;
use File::Copy::Recursive qw(rcopy); use File::Copy::Recursive qw(rcopy);
use File::Path qw(rmtree make_path); use File::Path qw(rmtree make_path);
use File::Which qw(which); use File::Which qw(which);
use Pod::Simple; use Pod::Simple;
use Pod::ParseLink;
use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations); use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations);
use Pod::Simple::HTMLBatch::Bugzilla; use Pod::Simple::Search;
use Pod::Simple::HTML::Bugzilla; use Pod::POM::View::Restructured;
use Tie::File;
use File::Spec::Functions qw(:ALL);
############################################################################### ###############################################################################
# Subs # Subs
############################################################################### ###############################################################################
my $error_found = 0; my $error_found = 0;
sub MakeDocs { sub MakeDocs {
my ($name, $cmdline) = @_; my ($name, $cmdline) = @_;
...@@ -56,38 +61,179 @@ sub MakeDocs { ...@@ -56,38 +61,179 @@ sub MakeDocs {
print "\n"; print "\n";
} }
sub make_pod { # Compile all the POD and make it part of the API docs
say "Creating API documentation..."; # Also duplicate some Extension docs into the User section, Admin section, and
# WebService docs
my $converter = Pod::Simple::HTMLBatch::Bugzilla->new; sub pod2rst {
# Don't output progress information. my $path = shift;
$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');
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);
} }
############################################################################### ###############################################################################
...@@ -95,10 +241,11 @@ END_HTML ...@@ -95,10 +241,11 @@ END_HTML
############################################################################### ###############################################################################
my @langs; my @langs;
# search for sub directories which have a 'rst' sub-directory # search for sub directories which have a 'rst' sub-directory
opendir(LANGS, './'); opendir(LANGS, './');
foreach my $dir (readdir(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") { if (-d "$dir/rst") {
push(@langs, $dir); push(@langs, $dir);
} }
...@@ -107,12 +254,19 @@ closedir(LANGS); ...@@ -107,12 +254,19 @@ closedir(LANGS);
my $docparent = getcwd(); my $docparent = getcwd();
foreach my $lang (@langs) { 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; next if grep { $_ eq '--pod-only' } @ARGV;
chdir "$docparent/$lang";
MakeDocs('HTML', 'html'); MakeDocs('HTML', 'html');
MakeDocs('TXT', 'text'); MakeDocs('TXT', 'text');
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment