IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Refactoring EPUB builders: split common codes from EPUB2 builder

Browse Source
This commit is contained in:
Yoshiki Shibukawa 2017-03-04 09:44:21 +09:00
parent 36f09e83d7
commit 7bbf749bd1
5 changed files with 116 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/builders.rst
View File

@ -125,8 +125,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: supported_image_types .. autoattribute:: supported_image_types
.. module:: sphinx.builders.epub .. module:: sphinx.builders.epub2
.. class:: EpubBuilder .. class:: Epub2Builder
This builder produces the same output as the standalone HTML builder, but 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 also generates an *epub* file for ebook readers. See :ref:`epub-faq` for

2
sphinx/application.py
View File

@ -65,7 +65,7 @@ if False:
builtin_extensions = ( builtin_extensions = (
'sphinx.builders.applehelp', 'sphinx.builders.applehelp',
'sphinx.builders.changes', 'sphinx.builders.changes',
'sphinx.builders.epub', 'sphinx.builders.epub2',
'sphinx.builders.epub3', 'sphinx.builders.epub3',
'sphinx.builders.devhelp', 'sphinx.builders.devhelp',
'sphinx.builders.dummy', 'sphinx.builders.dummy',

77
sphinx/builders/epub.py → sphinx/builders/_epub_base.py
View File

@ -1,10 +1,9 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
sphinx.builders.epub sphinx.builders._epub_base
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
Build epub files. Base class of epub2/epub3 builders.
Originally derived from qthelp.py.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS. :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details. :license: BSD, see LICENSE for details.
@ -12,7 +11,6 @@
import os import os
import re import re
import warnings
from os import path from os import path
from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
from datetime import datetime from datetime import datetime
@ -29,12 +27,10 @@ except ImportError:
from docutils import nodes from docutils import nodes
from sphinx import addnodes from sphinx import addnodes
from sphinx import package_dir
from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.deprecation import RemovedInSphinx17Warning
from sphinx.util import logging from sphinx.util import logging
from sphinx.util import status_iterator 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.fileutil import copy_asset_file
from sphinx.util.smartypants import sphinx_smarty_pants as ssp 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' TOCTREE_TEMPLATE = u'toctree-l%d'
DOCTYPE = u'''<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'''
LINK_TARGET_TEMPLATE = u' [%(uri)s]' LINK_TARGET_TEMPLATE = u' [%(uri)s]'
FOOTNOTE_LABEL_TEMPLATE = u'#%d' FOOTNOTE_LABEL_TEMPLATE = u'#%d'
@ -111,9 +104,6 @@ class EpubBuilder(StandaloneHTMLBuilder):
META-INF/container.xml. Afterwards, all necessary files are zipped to an META-INF/container.xml. Afterwards, all necessary files are zipped to an
epub file. epub file.
""" """
name = 'epub2'
template_dir = path.join(package_dir, 'templates', 'epub2')
# don't copy the reST source # don't copy the reST source
copysource = False copysource = False
@ -137,12 +127,13 @@ class EpubBuilder(StandaloneHTMLBuilder):
coverpage_name = COVERPAGE_NAME coverpage_name = COVERPAGE_NAME
toctree_template = TOCTREE_TEMPLATE toctree_template = TOCTREE_TEMPLATE
doctype = DOCTYPE
link_target_template = LINK_TARGET_TEMPLATE link_target_template = LINK_TARGET_TEMPLATE
css_link_target_class = CSS_LINK_TARGET_CLASS css_link_target_class = CSS_LINK_TARGET_CLASS
guide_titles = GUIDE_TITLES guide_titles = GUIDE_TITLES
media_types = MEDIA_TYPES media_types = MEDIA_TYPES
refuri_re = REFURI_RE refuri_re = REFURI_RE
template_dir = ""
doctype = ""
def init(self): def init(self):
# type: () -> None # type: () -> None
@ -453,17 +444,6 @@ class EpubBuilder(StandaloneHTMLBuilder):
StandaloneHTMLBuilder.handle_page(self, pagename, addctx, templatename, StandaloneHTMLBuilder.handle_page(self, pagename, addctx, templatename,
outfilename, event_arg) 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): def build_mimetype(self, outdir, outname):
# type: (unicode, unicode) -> None # type: (unicode, unicode) -> None
"""Write the metainfo file mimetype.""" """Write the metainfo file mimetype."""
@ -715,48 +695,3 @@ class EpubBuilder(StandaloneHTMLBuilder):
epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore
for filename in self.files: for filename in self.files:
epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore 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,
}

100
sphinx/builders/epub2.py Normal file
View File

@ -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 = '''<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">'''
# 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,
}

11
sphinx/builders/epub3.py
View File

@ -16,7 +16,7 @@ from collections import namedtuple
from sphinx import package_dir from sphinx import package_dir
from sphinx.config import string_classes, ENUM 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 import logging
from sphinx.util.fileutil import copy_asset_file from sphinx.util.fileutil import copy_asset_file
@ -45,10 +45,10 @@ THEME_WRITING_MODES = {
'horizontal': 'horizontal-tb', 'horizontal': 'horizontal-tb',
} }
DOCTYPE = u'''<!DOCTYPE html>''' DOCTYPE = '''<!DOCTYPE html>'''
class Epub3Builder(EpubBuilder): class Epub3Builder(_epub_base.EpubBuilder):
""" """
Builder that outputs epub3 files. Builder that outputs epub3 files.
@ -215,9 +215,12 @@ class Epub3Builder(EpubBuilder):
def setup(app): def setup(app):
# type: (Sphinx) -> Dict[unicode, Any] # type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.epub')
app.setup_extension('sphinx.builders.epub2')
app.add_builder(Epub3Builder) app.add_builder(Epub3Builder)
# config values
app.add_config_value('epub_description', 'unknown', 'epub3', string_classes) 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_contributor', 'unknown', 'epub3', string_classes)
app.add_config_value('epub_writing_mode', 'horizontal', 'epub3', app.add_config_value('epub_writing_mode', 'horizontal', 'epub3',