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

Merge pull request #5920 from tk0miya/refactor_applehelp

Browse Source 
Refactor applehelp builder
This commit is contained in:
Takeshi KOMIYA 2019-01-12 17:35:47 +09:00 committed by GitHub
commit c18c1546d7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 59 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
sphinx/builders/applehelp.py
View File

@ -8,21 +8,21 @@
:license: BSD, see LICENSE for details. :license: BSD, see LICENSE for details.
""" """
import html
import pipes
import plistlib import plistlib
import shlex import shlex
import subprocess import subprocess
from os import path, environ from os import path, environ
from subprocess import CalledProcessError, PIPE, STDOUT
from sphinx import package_dir
from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.errors import SphinxError from sphinx.errors import SphinxError
from sphinx.locale import __ from sphinx.locale import __
from sphinx.util import logging from sphinx.util import logging
from sphinx.util.console import bold # type: ignore from sphinx.util.console import bold # type: ignore
from sphinx.util.fileutil import copy_asset from sphinx.util.fileutil import copy_asset, copy_asset_file
from sphinx.util.matching import Matcher from sphinx.util.matching import Matcher
from sphinx.util.osutil import copyfile, ensuredir, make_filename from sphinx.util.osutil import ensuredir, make_filename
if False: if False:
# For type annotation # For type annotation
@ -31,22 +31,7 @@ if False:
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
template_dir = path.join(package_dir, 'templates', 'applehelp')
# False access page (used because helpd expects strict XHTML)
access_page_template = '''\
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>%(title)s</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="robots" content="noindex" />
<meta http-equiv="refresh" content="0;url=%(toc)s" />
</head>
<body>
</body>
</html>
'''
class AppleHelpIndexerFailed(SphinxError): class AppleHelpIndexerFailed(SphinxError):
@ -128,13 +113,17 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
resources_dir = path.join(contents_dir, 'Resources') resources_dir = path.join(contents_dir, 'Resources')
language_dir = path.join(resources_dir, language_dir = path.join(resources_dir,
self.config.applehelp_locale + '.lproj') self.config.applehelp_locale + '.lproj')
ensuredir(language_dir)
for d in [contents_dir, resources_dir, language_dir]: self.build_info_plist(contents_dir)
ensuredir(d) self.copy_applehelp_icon(resources_dir)
self.build_access_page(language_dir)
# Construct the Info.plist file self.build_helpindex(language_dir)
toc = self.config.master_doc + self.out_suffix self.do_codesign()
def build_info_plist(self, contents_dir):
# type: (str) -> None
"""Construct the Info.plist file."""
info_plist = { info_plist = {
'CFBundleDevelopmentRegion': self.config.applehelp_dev_region, 'CFBundleDevelopmentRegion': self.config.applehelp_dev_region,
'CFBundleIdentifier': self.config.applehelp_bundle_id, 'CFBundleIdentifier': self.config.applehelp_bundle_id,
@ -151,8 +140,7 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
} }
if self.config.applehelp_icon is not None: if self.config.applehelp_icon is not None:
info_plist['HPDBookIconPath'] \ info_plist['HPDBookIconPath'] = path.basename(self.config.applehelp_icon)
= path.basename(self.config.applehelp_icon)
if self.config.applehelp_kb_url is not None: if self.config.applehelp_kb_url is not None:
info_plist['HPDBookKBProduct'] = self.config.applehelp_kb_product info_plist['HPDBookKBProduct'] = self.config.applehelp_kb_product
@ -162,34 +150,37 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
info_plist['HPDBookRemoteURL'] = self.config.applehelp_remote_url info_plist['HPDBookRemoteURL'] = self.config.applehelp_remote_url
logger.info(bold(__('writing Info.plist... ')), nonl=True) logger.info(bold(__('writing Info.plist... ')), nonl=True)
with open(path.join(contents_dir, 'Info.plist'), 'wb') as fb: with open(path.join(contents_dir, 'Info.plist'), 'wb') as f:
plistlib.dump(info_plist, fb) plistlib.dump(info_plist, f)
logger.info(__('done')) logger.info(__('done'))
# Copy the icon, if one is supplied def copy_applehelp_icon(self, resources_dir):
# type: (str) -> None
"""Copy the icon, if one is supplied."""
if self.config.applehelp_icon: if self.config.applehelp_icon:
logger.info(bold(__('copying icon... ')), nonl=True) logger.info(bold(__('copying icon... ')), nonl=True)
try: try:
copyfile(path.join(self.srcdir, self.config.applehelp_icon), applehelp_icon = path.join(self.srcdir, self.config.applehelp_icon)
path.join(resources_dir, info_plist['HPDBookIconPath'])) copy_asset_file(applehelp_icon, resources_dir)
logger.info(__('done')) logger.info(__('done'))
except Exception as err: except Exception as err:
logger.warning(__('cannot copy icon file %r: %s'), logger.warning(__('cannot copy icon file %r: %s'), applehelp_icon, err)
path.join(self.srcdir, self.config.applehelp_icon), err)
del info_plist['HPDBookIconPath']
# Build the access page def build_access_page(self, language_dir):
# type: (str) -> None
"""Build the access page."""
logger.info(bold(__('building access page...')), nonl=True) logger.info(bold(__('building access page...')), nonl=True)
with open(path.join(language_dir, '_access.html'), 'w') as ft: context = {
ft.write(access_page_template % { 'toc': self.config.master_doc + self.out_suffix,
'toc': html.escape(toc, quote=True), 'title': self.config.applehelp_title,
'title': html.escape(self.config.applehelp_title) }
}) copy_asset_file(path.join(template_dir, '_access.html_t'), language_dir, context)
logger.info(__('done')) logger.info(__('done'))
# Generate the help index def build_helpindex(self, language_dir):
# type: (str) -> None
"""Generate the help index."""
logger.info(bold(__('generating help index... ')), nonl=True) logger.info(bold(__('generating help index... ')), nonl=True)
args = [ args = [
@ -213,25 +204,20 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
if self.config.applehelp_disable_external_tools: if self.config.applehelp_disable_external_tools:
logger.info(__('skipping')) logger.info(__('skipping'))
logger.warning(__('you will need to index this help book with:\n %s'), logger.warning(__('you will need to index this help book with:\n %s'),
' '.join([pipes.quote(arg) for arg in args])) ' '.join([shlex.quote(arg) for arg in args]))
else: else:
try: try:
p = subprocess.Popen(args, subprocess.run(args, stdout=PIPE, stderr=STDOUT, check=True)
stdout=subprocess.PIPE, logger.info(__('done'))
stderr=subprocess.STDOUT)
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpIndexerFailed(output)
else:
logger.info(__('done'))
except OSError: except OSError:
raise AppleHelpIndexerFailed(__('Command not found: %s') % args[0]) raise AppleHelpIndexerFailed(__('Command not found: %s') % args[0])
except CalledProcessError as exc:
raise AppleHelpCodeSigningFailed(exc.stdout)
# If we've been asked to, sign the bundle def do_codesign(self):
# type: () -> None
"""If we've been asked to, sign the bundle."""
if self.config.applehelp_codesign_identity: if self.config.applehelp_codesign_identity:
logger.info(bold(__('signing help book... ')), nonl=True) logger.info(bold(__('signing help book... ')), nonl=True)
@ -248,21 +234,15 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
if self.config.applehelp_disable_external_tools: if self.config.applehelp_disable_external_tools:
logger.info(__('skipping')) logger.info(__('skipping'))
logger.warning(__('you will need to sign this help book with:\n %s'), logger.warning(__('you will need to sign this help book with:\n %s'),
' '.join([pipes.quote(arg) for arg in args])) ' '.join([shlex.quote(arg) for arg in args]))
else: else:
try: try:
p = subprocess.Popen(args, subprocess.run(args, stdout=PIPE, stderr=STDOUT, check=True)
stdout=subprocess.PIPE, logger.info(__('done'))
stderr=subprocess.STDOUT)
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpCodeSigningFailed(output)
else:
logger.info(__('done'))
except OSError: except OSError:
raise AppleHelpCodeSigningFailed(__('Command not found: %s') % args[0]) raise AppleHelpCodeSigningFailed(__('Command not found: %s') % args[0])
except CalledProcessError as exc:
raise AppleHelpCodeSigningFailed(exc.stdout)
def setup(app): def setup(app):

12
sphinx/templates/applehelp/_access.html_t Normal file
View File

@ -0,0 +1,12 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>{{ title|e }}</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="robots" content="noindex" />
<meta http-equiv="refresh" content="0;url={{ toc|e }}" />
</head>
<body>
</body>
</html>