From 38c3cfbf27bf62e63e955cbab80783ea11b40b06 Mon Sep 17 00:00:00 2001 From: Frédéric Buclin Date: Tue, 21 Jan 2014 17:36:46 +0100 Subject: Bug 961398: Let rst2pdf build the PDF documentation if pdflatex is not available r=gerv a=glob --- docs/en/Makefile | 5 +++ docs/en/make.bat | 7 ++++ docs/en/rst/conf.py | 106 +++++++++++++++++++++++++++++++++++++++++++++++++- docs/en/rst/index.rst | 9 ----- docs/makedocs.pl | 17 +++++++- 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'; + } + } } -- cgit v1.2.3-24-g4f1b