diff options
Diffstat (limited to 'docs/makedocs.pl')
-rwxr-xr-x | docs/makedocs.pl | 83 |
1 files changed, 39 insertions, 44 deletions
diff --git a/docs/makedocs.pl b/docs/makedocs.pl index ea08d8258..74843c7a3 100755 --- a/docs/makedocs.pl +++ b/docs/makedocs.pl @@ -7,6 +7,19 @@ # 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) +# +# 2) 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; @@ -33,7 +46,7 @@ if (eval { require Pod::Simple }) { $pod_simple = 1; }; -use Bugzilla::Install::Requirements +use Bugzilla::Install::Requirements qw(REQUIRED_MODULES OPTIONAL_MODULES); use Bugzilla::Constants qw(DB_MODULE BUGZILLA_VERSION); @@ -46,15 +59,19 @@ my $opt_modules = OPTIONAL_MODULES; my $template; { - open(TEMPLATE, '<', 'bugzilla.ent.tmpl') - or die('Could not open bugzilla.ent.tmpl: ' . $!); + open(TEMPLATE, '<', 'definitions.rst.tmpl') + or die('Could not open definitions.rst.tmpl: ' . $!); local $/; $template = <TEMPLATE>; close TEMPLATE; } -open(ENTITIES, '>', 'bugzilla.ent') or die('Could not open bugzilla.ent: ' . $!); -print ENTITIES "$template\n"; -print ENTITIES '<!-- Module Versions -->' . "\n"; + +# This file is included at the end of Sphinx's conf.py. Unfortunately there's +# no way to 'epilog' a file, only text. +open(SUBSTS, '>', 'definitions.rst') or die('Could not open definitions.rst: ' . $!); +print SUBSTS 'rst_epilog = """' . "\n$template\n"; +print SUBSTS ".. Module Versions\n\n"; + foreach my $module (@$modules, @$opt_modules) { my $name = $module->{'module'}; @@ -63,10 +80,10 @@ foreach my $module (@$modules, @$opt_modules) #This needs to be a string comparison, due to the modules having #version numbers like 0.9.4 my $version = $module->{'version'} eq 0 ? 'any' : $module->{'version'}; - print ENTITIES '<!ENTITY min-' . $name . '-ver "'.$version.'">' . "\n"; + print SUBSTS '.. |min-' . $name . '-ver| replace:: ' . $version . "\n"; } -print ENTITIES "\n <!-- Database Versions --> \n"; +print SUBSTS "\n.. Database Versions\n\n"; my $db_modules = DB_MODULE; foreach my $db (keys %$db_modules) { @@ -76,28 +93,28 @@ foreach my $db (keys %$db_modules) { $name = lc($name); my $version = $dbd->{version} || 'any'; my $db_version = $db_modules->{$db}->{'db_version'}; - print ENTITIES '<!ENTITY min-' . $name . '-ver "'.$version.'">' . "\n"; - print ENTITIES '<!ENTITY min-' . lc($db) . '-ver "'.$db_version.'">' . "\n"; + print SUBSTS '.. |min-' . $name . '-ver| replace:: ' . $version . "\n"; + print SUBSTS '.. |min-' . lc($db) . '-ver| replace:: ' . $db_version . "\n"; } -close(ENTITIES); + +print SUBSTS '"""'; + +close(SUBSTS); ############################################################################### # Subs ############################################################################### sub MakeDocs { - my ($name, $cmdline) = @_; say "Creating $name documentation ..." if defined $name; say "$cmdline\n"; system $cmdline; print "\n"; - } sub make_pod { - say "Creating API documentation..."; my $converter = Pod::Simple::HTMLBatch::Bugzilla->new; @@ -122,9 +139,11 @@ END_HTML $converter->contents_page_start($contents_start); $converter->contents_page_end("</body></html>"); - $converter->add_css('./../../../style.css'); + $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"; @@ -135,11 +154,11 @@ END_HTML ############################################################################### my @langs; -# search for sub directories which have a 'xml' sub-directory +# 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/xml") { + if (-d "$dir/rst") { push(@langs, $dir); } } @@ -148,34 +167,10 @@ closedir(LANGS); my $docparent = getcwd(); foreach my $lang (@langs) { chdir "$docparent/$lang"; - MakeDocs(undef, 'cp ../bugzilla.ent ./xml/'); - - if (!-d 'txt') { - unlink 'txt'; - mkdir 'txt', 0755; - } - if (!-d 'pdf') { - unlink 'pdf'; - mkdir 'pdf', 0755; - } - if (!-d 'html') { - unlink 'html'; - mkdir 'html', 0755; - } - if (!-d 'html/api') { - unlink 'html/api'; - mkdir 'html/api', 0755; - } make_pod() if $pod_simple; - MakeDocs('separate HTML', 'xmlto -m ../xsl/chunks.xsl -o html html xml/Bugzilla-Guide.xml'); - MakeDocs('big HTML', 'xmlto -m ../xsl/nochunks.xsl -o html html-nochunks xml/Bugzilla-Guide.xml'); - MakeDocs('big text', 'lynx -dump -justify=off -nolist html/Bugzilla-Guide.html > txt/Bugzilla-Guide.txt'); - - if (! grep($_ eq "--with-pdf", @ARGV)) { - next; - } - - MakeDocs('PDF', 'dblatex -p ../xsl/pdf.xsl -o pdf/Bugzilla-Guide.pdf xml/Bugzilla-Guide.xml'); + MakeDocs('HTML', 'make html'); + MakeDocs('TXT', 'make text'); + MakeDocs('PDF', 'make latexpdf'); } |