Merge pull request #5910 from tk0miya/refactor_epub

Refactor epub builder: deprecate arguments of build_* method.
This commit is contained in:
Takeshi KOMIYA 2019-01-12 17:47:08 +09:00 committed by GitHub
commit 51d6a096fb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 69 additions and 12 deletions

View File

@ -58,6 +58,10 @@ Deprecated
* Support for evaluating Python 2 syntax is deprecated. This includes
configuration files which should be converted to Python 3.
* The arguments of ``EpubBuilder.build_mimetype()``,
``EpubBuilder.build_container()``, ``EpubBuilder.bulid_content()``,
``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
* The arguments of ``Epub3Builder.build_navigation_doc()``
* The ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
``autodoc.DocstringSignatureMixin.get_doc()``,
``autodoc.DocstringSignatureMixin._find_signature()``, and

View File

@ -242,6 +242,18 @@ The following is a list of deprecated interfaces.
- 4.0
- N/A
* - arguments of ``EpubBuilder.build_mimetype()``,
``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``,
``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
- 2.0
- 4.0
- N/A
* - arguments of ``Epub3Builder.build_navigation_doc()``
- 2.0
- 4.0
- N/A
* - ``nodetype`` argument of
``sphinx.search.WordCollector.is_meta_keywords()``
- 2.0

View File

@ -10,6 +10,7 @@
import os
import re
import warnings
from collections import namedtuple
from os import path
from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
@ -19,6 +20,7 @@ from docutils.utils import smartquotes
from sphinx import addnodes
from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.locale import __
from sphinx.util import logging
from sphinx.util import status_iterator
@ -470,16 +472,28 @@ class EpubBuilder(StandaloneHTMLBuilder):
addctx['doctype'] = self.doctype
super().handle_page(pagename, addctx, templatename, outfilename, event_arg)
def build_mimetype(self, outdir, outname):
def build_mimetype(self, outdir=None, outname='mimetype'):
# type: (str, str) -> None
"""Write the metainfo file mimetype."""
if outdir:
warnings.warn('The arguments of EpubBuilder.build_mimetype() is deprecated.',
RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
logger.info(__('writing %s file...'), outname)
copy_asset_file(path.join(self.template_dir, 'mimetype'),
path.join(outdir, outname))
def build_container(self, outdir, outname):
def build_container(self, outdir=None, outname='META-INF/container.xml'):
# type: (str, str) -> None
"""Write the metainfo file META-INF/container.xml."""
if outdir:
warnings.warn('The arguments of EpubBuilder.build_container() is deprecated.',
RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
logger.info(__('writing %s file...'), outname)
filename = path.join(outdir, outname)
ensuredir(path.dirname(filename))
@ -505,11 +519,17 @@ class EpubBuilder(StandaloneHTMLBuilder):
metadata['guides'] = []
return metadata
def build_content(self, outdir, outname):
def build_content(self, outdir=None, outname='content.opf'):
# type: (str, str) -> None
"""Write the metainfo file content.opf It contains bibliographic data,
a file list and the spine (the reading order).
"""
if outdir:
warnings.warn('The arguments of EpubBuilder.build_content() is deprecated.',
RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
logger.info(__('writing %s file...'), outname)
metadata = self.content_metadata()
@ -686,9 +706,15 @@ class EpubBuilder(StandaloneHTMLBuilder):
metadata['navpoints'] = navpoints
return metadata
def build_toc(self, outdir, outname):
def build_toc(self, outdir=None, outname='toc.ncx'):
# type: (str, str) -> None
"""Write the metainfo file toc.ncx."""
if outdir:
warnings.warn('The arguments of EpubBuilder.build_toc() is deprecated.',
RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
logger.info(__('writing %s file...'), outname)
if self.config.epub_tocscope == 'default':
@ -707,13 +733,20 @@ class EpubBuilder(StandaloneHTMLBuilder):
path.join(outdir, outname),
self.toc_metadata(level, navpoints))
def build_epub(self, outdir, outname):
def build_epub(self, outdir=None, outname=None):
# type: (str, str) -> None
"""Write the epub file.
It is a zip file with the mimetype file stored uncompressed as the first
entry.
"""
if outdir:
warnings.warn('The arguments of EpubBuilder.build_epub() is deprecated.',
RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
outname = self.config.epub_basename + '.epub'
logger.info(__('writing %s file...'), outname)
epub_filename = path.join(outdir, outname)
with ZipFile(epub_filename, 'w', ZIP_DEFLATED) as epub:

View File

@ -9,12 +9,14 @@
:license: BSD, see LICENSE for details.
"""
import warnings
from collections import namedtuple
from os import path
from sphinx import package_dir
from sphinx.builders import _epub_base
from sphinx.config import ENUM
from sphinx.deprecation import RemovedInSphinx40Warning
from sphinx.locale import __
from sphinx.util import logging, xmlname_checker
from sphinx.util.fileutil import copy_asset_file
@ -78,12 +80,12 @@ class Epub3Builder(_epub_base.EpubBuilder):
"""Create the metainfo files and finally the epub."""
self.validate_config_value()
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_navigation_doc(self.outdir, 'nav.xhtml')
self.build_toc(self.outdir, 'toc.ncx')
self.build_epub(self.outdir, self.config.epub_basename + '.epub')
self.build_mimetype()
self.build_container()
self.build_content()
self.build_navigation_doc()
self.build_toc()
self.build_epub()
def validate_config_value(self):
# type: () -> None
@ -202,9 +204,15 @@ class Epub3Builder(_epub_base.EpubBuilder):
metadata['navlist'] = navlist
return metadata
def build_navigation_doc(self, outdir, outname):
def build_navigation_doc(self, outdir=None, outname='nav.xhtml'):
# type: (str, str) -> None
"""Write the metainfo file nav.xhtml."""
if outdir:
warnings.warn('The arguments of Epub3Builder.build_navigation_doc() '
'is deprecated.', RemovedInSphinx40Warning, stacklevel=2)
else:
outdir = self.outdir
logger.info(__('writing %s file...'), outname)
if self.config.epub_tocscope == 'default':