#!/usr/bin/perl # This Source Code Form is subject to the terms of the Mozilla Public # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at http://mozilla.org/MPL/2.0/. # # This Source Code Form is "Incompatible With Secondary Licenses", as # defined by the Mozilla Public License, v. 2.0. # This script compiles all the documentation. # # Required software: # # 1) Sphinx documentation builder (python-sphinx package on Debian/Ubuntu) # # 2a) rst2pdf # or # 2b) pdflatex, which means the following Debian/Ubuntu packages: # * texlive-latex-base # * texlive-latex-recommended # * texlive-latex-extra # * texlive-fonts-recommended # # All these TeX packages together are close to a gig :-| But after you've # installed them, you can remove texlive-latex-extra-doc to save 400MB. use 5.10.1; use strict; use warnings; use File::Basename; BEGIN { chdir dirname($0); } use lib qw(.. ../lib lib); use Cwd; use File::Copy qw(copy); use File::Copy::Recursive qw(rcopy); use File::Find; use File::Path qw(rmtree make_path); use File::Which qw(which); use Pod::Simple; use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations); use Pod::Simple::HTMLBatch::Bugzilla; use Pod::Simple::HTML::Bugzilla; ############################################################################### # Subs ############################################################################### my $error_found = 0; sub MakeDocs { my ($name, $cmdline) = @_; say "Creating $name documentation ..." if defined $name; system('make', $cmdline) == 0 or $error_found = 1; 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 = < $content_type Bugzilla $bz_version API Documentation

Bugzilla $bz_version API Documentation

END_HTML $converter->contents_page_start($contents_start); $converter->contents_page_end(""); if (exists($::ENV{'READTHEDOCS'})) { $converter->add_css('./../../style.css'); } else { $converter->add_css('./../../../../style.css'); } $converter->javascript_flurry(0); $converter->css_flurry(0); make_path('html/integrating/api'); $converter->batch_convert(['../../'], 'html/integrating/api'); if (exists($::ENV{'READTHEDOCS'})) { copy('../style.css', 'html/style.css') or die "Copy failed: $!"; } print "\n"; } ############################################################################### # Make the docs ... ############################################################################### 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); } } closedir(LANGS); my $docparent = getcwd(); foreach my $lang (@langs) { chdir "$docparent/$lang"; make_pod(); next if grep { $_ eq '--pod-only' } @ARGV; 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"; } } # 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); } 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); } die "Error occurred building the documentation\n" if $error_found;