makedocs.pl

#!/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::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 = <<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";
}

###############################################################################
# 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;