diff --git a/doc/builders.rst b/doc/builders.rst index 2d17abc7d..618eb005c 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -125,8 +125,8 @@ The builder's "name" must be given to the **-b** command-line option of .. autoattribute:: supported_image_types -.. module:: sphinx.builders.epub -.. class:: EpubBuilder +.. module:: sphinx.builders.epub2 +.. class:: Epub2Builder This builder produces the same output as the standalone HTML builder, but also generates an *epub* file for ebook readers. See :ref:`epub-faq` for diff --git a/sphinx/application.py b/sphinx/application.py index 80c96d280..1a575eb2d 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -65,7 +65,7 @@ if False: builtin_extensions = ( 'sphinx.builders.applehelp', 'sphinx.builders.changes', - 'sphinx.builders.epub', + 'sphinx.builders.epub2', 'sphinx.builders.epub3', 'sphinx.builders.devhelp', 'sphinx.builders.dummy', diff --git a/sphinx/builders/epub.py b/sphinx/builders/_epub_base.py similarity index 90% rename from sphinx/builders/epub.py rename to sphinx/builders/_epub_base.py index 5b3c41b24..532384173 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/_epub_base.py @@ -1,10 +1,9 @@ # -*- coding: utf-8 -*- """ - sphinx.builders.epub - ~~~~~~~~~~~~~~~~~~~~ + sphinx.builders._epub_base + ~~~~~~~~~~~~~~~~~~~~~~~~~~ - Build epub files. - Originally derived from qthelp.py. + Base class of epub2/epub3 builders. :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. @@ -12,7 +11,6 @@ import os import re -import warnings from os import path from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile from datetime import datetime @@ -29,12 +27,10 @@ except ImportError: from docutils import nodes from sphinx import addnodes -from sphinx import package_dir from sphinx.builders.html import StandaloneHTMLBuilder -from sphinx.deprecation import RemovedInSphinx17Warning from sphinx.util import logging from sphinx.util import status_iterator -from sphinx.util.osutil import ensuredir, copyfile, make_filename +from sphinx.util.osutil import ensuredir, copyfile from sphinx.util.fileutil import copy_asset_file from sphinx.util.smartypants import sphinx_smarty_pants as ssp @@ -57,9 +53,6 @@ COVERPAGE_NAME = u'epub-cover.xhtml' TOCTREE_TEMPLATE = u'toctree-l%d' -DOCTYPE = u'''''' - LINK_TARGET_TEMPLATE = u' [%(uri)s]' FOOTNOTE_LABEL_TEMPLATE = u'#%d' @@ -111,9 +104,6 @@ class EpubBuilder(StandaloneHTMLBuilder): META-INF/container.xml. Afterwards, all necessary files are zipped to an epub file. """ - name = 'epub2' - - template_dir = path.join(package_dir, 'templates', 'epub2') # don't copy the reST source copysource = False @@ -137,12 +127,13 @@ class EpubBuilder(StandaloneHTMLBuilder): coverpage_name = COVERPAGE_NAME toctree_template = TOCTREE_TEMPLATE - doctype = DOCTYPE link_target_template = LINK_TARGET_TEMPLATE css_link_target_class = CSS_LINK_TARGET_CLASS guide_titles = GUIDE_TITLES media_types = MEDIA_TYPES refuri_re = REFURI_RE + template_dir = "" + doctype = "" def init(self): # type: () -> None @@ -453,17 +444,6 @@ class EpubBuilder(StandaloneHTMLBuilder): StandaloneHTMLBuilder.handle_page(self, pagename, addctx, templatename, outfilename, event_arg) - # Finish by building the epub file - def handle_finish(self): - # type: () -> None - """Create the metainfo files and finally the epub.""" - self.get_toc() - self.build_mimetype(self.outdir, 'mimetype') - self.build_container(self.outdir, 'META-INF/container.xml') - self.build_content(self.outdir, 'content.opf') - self.build_toc(self.outdir, 'toc.ncx') - self.build_epub(self.outdir, self.config.epub_basename + '.epub') - def build_mimetype(self, outdir, outname): # type: (unicode, unicode) -> None """Write the metainfo file mimetype.""" @@ -715,48 +695,3 @@ class EpubBuilder(StandaloneHTMLBuilder): epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore for filename in self.files: epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore - - -def emit_deprecation_warning(app): - # type: (Sphinx) -> None - if app.builder.__class__ is EpubBuilder: - warnings.warn('epub2 builder is deprecated. Please use epub3 builder instead.', - RemovedInSphinx17Warning) - - -def setup(app): - # type: (Sphinx) -> Dict[unicode, Any] - app.setup_extension('sphinx.builders.html') - app.add_builder(EpubBuilder) - app.connect('builder-inited', emit_deprecation_warning) - - # config values - app.add_config_value('epub_basename', lambda self: make_filename(self.project), None) - app.add_config_value('epub_theme', 'epub', 'html') - app.add_config_value('epub_theme_options', {}, 'html') - app.add_config_value('epub_title', lambda self: self.html_title, 'html') - app.add_config_value('epub_author', 'unknown', 'html') - app.add_config_value('epub_language', lambda self: self.language or 'en', 'html') - app.add_config_value('epub_publisher', 'unknown', 'html') - app.add_config_value('epub_copyright', lambda self: self.copyright, 'html') - app.add_config_value('epub_identifier', 'unknown', 'html') - app.add_config_value('epub_scheme', 'unknown', 'html') - app.add_config_value('epub_uid', 'unknown', 'env') - app.add_config_value('epub_cover', (), 'env') - app.add_config_value('epub_guide', (), 'env') - app.add_config_value('epub_pre_files', [], 'env') - app.add_config_value('epub_post_files', [], 'env') - app.add_config_value('epub_exclude_files', [], 'env') - app.add_config_value('epub_tocdepth', 3, 'env') - app.add_config_value('epub_tocdup', True, 'env') - app.add_config_value('epub_tocscope', 'default', 'env') - app.add_config_value('epub_fix_images', False, 'env') - app.add_config_value('epub_max_image_width', 0, 'env') - app.add_config_value('epub_show_urls', 'inline', 'html') - app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'html') - - return { - 'version': 'builtin', - 'parallel_read_safe': True, - 'parallel_write_safe': True, - } diff --git a/sphinx/builders/epub2.py b/sphinx/builders/epub2.py new file mode 100644 index 000000000..a6dcc8568 --- /dev/null +++ b/sphinx/builders/epub2.py @@ -0,0 +1,100 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.epub2 + ~~~~~~~~~~~~~~~~~~~~~ + + Build epub2 files. + Originally derived from qthelp.py. + + :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import warnings +from os import path + +from sphinx import package_dir +from sphinx.builders import _epub_base +from sphinx.util.osutil import make_filename +from sphinx.deprecation import RemovedInSphinx17Warning + +if False: + # For type annotation + from typing import Any, Dict # NOQA + from sphinx.application import Sphinx # NOQA + + +DOCTYPE = '''''' + + +# The epub publisher + +class Epub2Builder(_epub_base.EpubBuilder): + """ + Builder that outputs epub files. + + It creates the metainfo files container.opf, toc.ncx, mimetype, and + META-INF/container.xml. Afterwards, all necessary files are zipped to an + epub file. + """ + name = 'epub2' + + template_dir = path.join(package_dir, 'templates', 'epub2') + doctype = DOCTYPE + + # Finish by building the epub file + def handle_finish(self): + # type: () -> None + """Create the metainfo files and finally the epub.""" + self.get_toc() + self.build_mimetype(self.outdir, 'mimetype') + self.build_container(self.outdir, 'META-INF/container.xml') + self.build_content(self.outdir, 'content.opf') + self.build_toc(self.outdir, 'toc.ncx') + self.build_epub(self.outdir, self.config.epub_basename + '.epub') + + +def emit_deprecation_warning(app): + # type: (Sphinx) -> None + if app.builder.__class__ is Epub2Builder: + warnings.warn('epub2 builder is deprecated. Please use epub3 builder instead.', + RemovedInSphinx17Warning) + + +def setup(app): + # type: (Sphinx) -> Dict[unicode, Any] + app.setup_extension('sphinx.builders.html') + app.add_builder(Epub2Builder) + app.connect('builder-inited', emit_deprecation_warning) + + # config values + app.add_config_value('epub_basename', lambda self: make_filename(self.project), None) + app.add_config_value('epub_theme', 'epub', 'html') + app.add_config_value('epub_theme_options', {}, 'html') + app.add_config_value('epub_title', lambda self: self.html_title, 'html') + app.add_config_value('epub_author', 'unknown', 'html') + app.add_config_value('epub_language', lambda self: self.language or 'en', 'html') + app.add_config_value('epub_publisher', 'unknown', 'html') + app.add_config_value('epub_copyright', lambda self: self.copyright, 'html') + app.add_config_value('epub_identifier', 'unknown', 'html') + app.add_config_value('epub_scheme', 'unknown', 'html') + app.add_config_value('epub_uid', 'unknown', 'env') + app.add_config_value('epub_cover', (), 'env') + app.add_config_value('epub_guide', (), 'env') + app.add_config_value('epub_pre_files', [], 'env') + app.add_config_value('epub_post_files', [], 'env') + app.add_config_value('epub_exclude_files', [], 'env') + app.add_config_value('epub_tocdepth', 3, 'env') + app.add_config_value('epub_tocdup', True, 'env') + app.add_config_value('epub_tocscope', 'default', 'env') + app.add_config_value('epub_fix_images', False, 'env') + app.add_config_value('epub_max_image_width', 0, 'env') + app.add_config_value('epub_show_urls', 'inline', 'html') + app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'html') + + return { + 'version': 'builtin', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py index 8d5118a6d..a64493552 100644 --- a/sphinx/builders/epub3.py +++ b/sphinx/builders/epub3.py @@ -16,7 +16,7 @@ from collections import namedtuple from sphinx import package_dir from sphinx.config import string_classes, ENUM -from sphinx.builders.epub import EpubBuilder +from sphinx.builders import _epub_base from sphinx.util import logging from sphinx.util.fileutil import copy_asset_file @@ -45,10 +45,10 @@ THEME_WRITING_MODES = { 'horizontal': 'horizontal-tb', } -DOCTYPE = u'''''' +DOCTYPE = '''''' -class Epub3Builder(EpubBuilder): +class Epub3Builder(_epub_base.EpubBuilder): """ Builder that outputs epub3 files. @@ -215,9 +215,12 @@ class Epub3Builder(EpubBuilder): def setup(app): # type: (Sphinx) -> Dict[unicode, Any] - app.setup_extension('sphinx.builders.epub') + + app.setup_extension('sphinx.builders.epub2') + app.add_builder(Epub3Builder) + # config values app.add_config_value('epub_description', 'unknown', 'epub3', string_classes) app.add_config_value('epub_contributor', 'unknown', 'epub3', string_classes) app.add_config_value('epub_writing_mode', 'horizontal', 'epub3',