summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorFrédéric Buclin <LpSolit@gmail.com>2014-01-21 17:36:46 +0100
committerFrédéric Buclin <LpSolit@gmail.com>2014-01-21 17:36:46 +0100
commit38c3cfbf27bf62e63e955cbab80783ea11b40b06 (patch)
tree213302271de3b5499e6803f461084bd79c94bb1a /docs
parent91ae795be29e4ab48da994e1e33c21b2d3c524b5 (diff)
downloadbugzilla-38c3cfbf27bf62e63e955cbab80783ea11b40b06.tar.gz
bugzilla-38c3cfbf27bf62e63e955cbab80783ea11b40b06.tar.xz
Bug 961398: Let rst2pdf build the PDF documentation if pdflatex is not available
r=gerv a=glob
Diffstat (limited to 'docs')
-rw-r--r--docs/en/Makefile5
-rw-r--r--docs/en/make.bat7
-rw-r--r--docs/en/rst/conf.py106
-rw-r--r--docs/en/rst/index.rst9
-rwxr-xr-xdocs/makedocs.pl17
5 files changed, 132 insertions, 12 deletions
diff --git a/docs/en/Makefile b/docs/en/Makefile
index afbe6ee26..c0708059d 100644
--- a/docs/en/Makefile
+++ b/docs/en/Makefile
@@ -108,6 +108,11 @@ latexpdf:
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+pdf:
+ $(SPHINXBUILD) -b pdf -t enable_rst2pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
+ @echo
+ @echo "Build finished. The PDF file is in $(BUILDDIR)/pdf."
+
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/txt
@echo
diff --git a/docs/en/make.bat b/docs/en/make.bat
index 5c1494bf7..c12f0a720 100644
--- a/docs/en/make.bat
+++ b/docs/en/make.bat
@@ -187,4 +187,11 @@ results in %BUILDDIR%/doctest/output.txt.
goto end
)
+if "%1" == "pdf" (
+ %SPHINXBUILD% -b pdf -t enable_rst2pdf %ALLSPHINXOPTS% %BUILDDIR%/pdf
+ echo.
+ echo.Build finished. The PDF file is in %BUILDDIR%/pdf
+ goto end
+)
+
:end
diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py
index 159226809..1d8d0e909 100644
--- a/docs/en/rst/conf.py
+++ b/docs/en/rst/conf.py
@@ -27,6 +27,9 @@ import sys, os
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.todo']
+if tags.has('enable_rst2pdf'):
+ extensions.append('rst2pdf.pdfbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -115,7 +118,7 @@ html_theme = 'default'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-#html_favicon = None
+html_favicon = '../../../images/favicon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
@@ -147,7 +150,7 @@ html_static_path = ['_static']
#html_split_index = False
# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
@@ -244,3 +247,102 @@ texinfo_documents = [
definitions = "../../definitions.rst"
if os.path.exists(definitions):
execfile(definitions)
+
+
+# -- Options for PDF output --------------------------------------------------
+
+# Grouping the document tree into PDF files. List of tuples
+# (source start file, target name, title, author, options).
+#
+# If there is more than one author, separate them with \\.
+# For example: r'Guido van Rossum\\Fred L. Drake, Jr., editor'
+#
+# The options element is a dictionary that lets you override
+# this config per-document.
+# For example,
+# ('index', u'MyProject', u'My Project', u'Author Name',
+# dict(pdf_compressed = True))
+# would mean that specific document would be compressed
+# regardless of the global pdf_compressed setting.
+
+pdf_documents = [
+('index', u'Bugzilla', u'Bugzilla Documentation', u'The Bugzilla Team'),
+]
+
+# A comma-separated list of custom stylesheets. Example:
+pdf_stylesheets = ['sphinx','kerning','a4']
+
+# A list of folders to search for stylesheets. Example:
+pdf_style_path = ['.', '_styles']
+
+# Create a compressed PDF
+# Use True/False or 1/0
+# Example: compressed=True
+pdf_compressed = True
+
+# A colon-separated list of folders to search for fonts. Example:
+# pdf_font_path = ['/usr/share/fonts', '/usr/share/texmf-dist/fonts/']
+
+# Language to be used for hyphenation support
+#pdf_language = "en_US"
+
+# Mode for literal blocks wider than the frame. Can be
+# overflow, shrink or truncate
+pdf_fit_mode = "shrink"
+
+# Section level that forces a break page.
+# For example: 1 means top-level sections start in a new page
+# 0 means disabled
+pdf_break_level = 2
+
+# When a section starts in a new page, force it to be 'even', 'odd',
+# or just use 'any'
+#pdf_breakside = 'any'
+
+# Insert footnotes where they are defined instead of
+# at the end.
+#pdf_inline_footnotes = True
+
+# verbosity level. 0 1 or 2
+pdf_verbosity = 0
+
+# If false, no index is generated.
+pdf_use_index = False
+
+# If false, no modindex is generated.
+pdf_use_modindex = False
+
+# If false, no coverpage is generated.
+#pdf_use_coverpage = True
+
+# Name of the cover page template to use
+#pdf_cover_template = 'sphinxcover.tmpl'
+
+# Documents to append as an appendix to all manuals.
+#pdf_appendices = []
+
+# Enable experimental feature to split table cells. Use it
+# if you get "DelayedTable too big" errors
+#pdf_splittables = False
+
+# Set the default DPI for images
+#pdf_default_dpi = 72
+
+# Enable rst2pdf extension modules (default is only vectorpdf)
+# you need vectorpdf if you want to use sphinx's graphviz support
+pdf_extensions = ['vectorpdf', 'dotted_toc']
+
+# Page template name for "regular" pages
+#pdf_page_template = 'cutePage'
+
+# Show Table Of Contents at the beginning?
+pdf_use_toc = True
+
+# How many levels deep should the table of contents be?
+pdf_toc_depth = 5
+
+# Add section number to section references
+pdf_use_numbered_links = True
+
+# Background images fitting mode
+pdf_fit_background_mode = 'scale'
diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index d7d7bf94c..b98b0a1d5 100644
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -6,8 +6,6 @@
Bugzilla Documentation
======================
-Contents:
-
.. toctree::
:maxdepth: 3
:numbered:
@@ -23,10 +21,3 @@ Contents:
modules
gfdl
glossary
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index e46f7e7da..2fc6721eb 100755
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -50,6 +50,9 @@ use Bugzilla::Install::Requirements
qw(REQUIRED_MODULES OPTIONAL_MODULES);
use Bugzilla::Constants qw(DB_MODULE BUGZILLA_VERSION);
+use File::Path qw(rmtree);
+use File::Which qw(which);
+
###############################################################################
# Generate minimum version list
###############################################################################
@@ -174,5 +177,17 @@ foreach my $lang (@langs) {
MakeDocs('HTML', 'make html');
MakeDocs('TXT', 'make text');
- MakeDocs('PDF', 'make latexpdf') if grep { $_ eq '--with-pdf' } @ARGV;
+
+ if (grep { $_ eq '--with-pdf' } @ARGV) {
+ if (which('pdflatex')) {
+ MakeDocs('PDF', 'make latexpdf');
+ }
+ elsif (which('rst2pdf')) {
+ rmtree('pdf', 0, 1);
+ MakeDocs('PDF', 'make pdf');
+ }
+ else {
+ say 'pdflatex or rst2pdf not found. Skipping PDF file creation';
+ }
+ }
}