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

Added some additional configuration variables for Apple Help.

Browse Source 
Removed Apple Help from quickstart conf.py.
Added support for .lproj directories with pre-localised files for Apple Help.
This commit is contained in:
Alastair Houghton
2015-01-15 13:11:58 +00:00
parent be46a14984
commit 5aa7f6bd80
6 changed files with 111 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
doc/builders.rst
View File

@@ -82,9 +82,17 @@ The builder's "name" must be given to the **-b** command-line option of
This builder produces an Apple Help Book based on the same output as the
standalone HTML builder.
This builder requires Mac OS X 10.6 or higher to function, as it depends on
the command line tools :program:`hiutil` and :program:`codesign`, neither
of which is Open Source.
If the source directory contains any ``.lproj`` folders, the one
corresponding to the selected language will have its contents merged with
the generated output. These folders will be ignored by all other
documentation types.
In order to generate a valid help book, this builder requires the command
line tool :program:`hiutil`, which is only available on Mac OS X 10.6 and
above. You can disable the indexing step by setting
:confval:`applehelp_disable_external_tools` to ``True``, in which case the
output will not be valid until :program:`hiutil` has been run on all of the
``.lproj`` folders within the bundle.
.. autoattribute:: name

39
doc/config.rst
View File

@@ -904,6 +904,8 @@ that use Sphinx's HTMLWriter class.
Options for Apple Help output
-----------------------------
.. versionadded:: 1.3
These options influence the Apple Help output. This builder derives from the
HTML builder, so the HTML options also apply where appropriate.
@@ -913,6 +915,11 @@ HTML builder, so the HTML options also apply where appropriate.
requires the :program:`hiutil` and :program:`codesign` command line tools,
neither of which are Open Source.
You can disable the use of these tools using
:confval:`applehelp_disable_external_tools`, but the result will not be a
valid help book until the indexer is run over the ``.lproj`` folders within
the bundle.
.. confval:: applehelp_bundle_name
The basename for the Apple Help Book. Defaults to the :confval:`project`
@@ -920,8 +927,11 @@ HTML builder, so the HTML options also apply where appropriate.
.. confval:: applehelp_bundle_id
The bundle ID for the help book bundle. Defaults to
:samp:`'com.mycompany.{<project>}.help'`.
The bundle ID for the help book bundle.
.. warning::
You *must* set this value in order to generate Apple Help.
.. confval:: applehelp_dev_region
@@ -1024,13 +1034,34 @@ HTML builder, so the HTML options also apply where appropriate.
.. confval:: applehelp_codesign_flags
A *list* of additional arguments to pass to ``codesign`` when signing the
help book.
A *list* of additional arguments to pass to :program:`codesign` when
signing the help book.
Defaults to a list based on the value of the environment variable
``OTHER_CODE_SIGN_FLAGS``, which is set by Xcode for script build phases,
or the empty list if that variable is not set.
.. confval:: applehelp_indexer_path
The path to the :program:`hiutil` program. Defaults to
``'/usr/bin/hiutil'``.
.. confval:: applehelp_codesign_path
The path to the :program:`codesign` program. Defaults to
``'/usr/bin/codesign'``.
.. confval:: applehelp_disable_external_tools
If ``True``, the builder will not run the indexer or the code signing tool,
no matter what other settings are specified.
This is mainly useful for testing, or where you want to run the Sphinx
build on a non-Mac OS X platform and then complete the final steps on OS X
for some reason.
Defaults to ``False``.
.. _epub-options:

83
sphinx/builders/applehelp.py
View File

@@ -13,13 +13,16 @@ from __future__ import print_function
import os
import codecs
import errno
import pipes
from os import path
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.util import copy_static_entry
from sphinx.util.osutil import copyfile, ensuredir, os_path
from sphinx.util.console import bold
from sphinx.util.pycompat import htmlescape
from sphinx.util.matching import compile_matchers
from sphinx.errors import SphinxError
import plistlib
@@ -55,7 +58,7 @@ class AppleHelpIndexerFailed(SphinxError):
class AppleHelpCodeSigningFailed(SphinxError):
category = 'Code signing failed'
class AppleHelpBuilder(StandaloneHTMLBuilder):
"""
@@ -72,8 +75,8 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
# don't add links
add_permalinks = False
# *do* add the sidebar (Apple Help doesn't have its own)
embedded = False
# this is an embedded HTML format
embedded = True
# don't generate the search index or include the search page
search = False
@@ -83,6 +86,10 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
# the output files for HTML help must be .html only
self.out_suffix = '.html'
if self.config.applehelp_bundle_id is None:
raise SphinxError('You must set applehelp_bundle_id before ' \
'building Apple Help output')
self.bundle_path = path.join(self.outdir,
self.config.applehelp_bundle_name \
+ '.help')
@@ -93,9 +100,25 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
def handle_finish(self):
super(AppleHelpBuilder, self).handle_finish()
self.finish_tasks.add_task(self.build_helpbook)
self.finish_tasks.add_task(self.copy_localized_files)
self.finish_tasks.add_task(self.build_helpbook)
def copy_localized_files(self):
source_dir = path.join(self.confdir,
self.config.applehelp_locale + '.lproj')
target_dir = self.outdir
if path.isdir(source_dir):
self.info(bold('copying localized files... '), nonl=True)
ctx = self.globalcontext.copy()
matchers = compile_matchers(self.config.exclude_patterns)
copy_static_entry(source_dir, target_dir, self, ctx,
exclude_matchers=matchers)
self.info('done')
def build_helpbook(self):
contents_dir = path.join(self.bundle_path, 'Contents')
resources_dir = path.join(contents_dir, 'Resources')
@@ -168,12 +191,12 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
finally:
f.close()
self.info('done')
# Generate the help index
self.info(bold('generating help index... '), nonl=True)
args = [
'/usr/bin/hiutil',
self.config.applehelp_indexer_path,
'-Cf',
path.join(language_dir, 'search.helpindex'),
language_dir
@@ -191,23 +214,29 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
if self.config.applehelp_locale is not None:
args += ['-l', self.config.applehelp_locale]
p = subprocess.Popen(args,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
if self.config.applehelp_disable_external_tools:
self.info('skipping')
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpIndexerFailed(output)
self.warn('you will need to index this help book with:\n %s'
% (' '.join([pipes.quote(arg) for arg in args])))
else:
self.info('done')
p = subprocess.Popen(args,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpIndexerFailed(output)
else:
self.info('done')
# If we've been asked to, sign the bundle
if self.config.applehelp_codesign_identity:
self.info(bold('signing help book... '), nonl=True)
args = [
'/usr/bin/codesign',
self.config.applehelp_codesign_path,
'-s', self.config.applehelp_codesign_identity,
'-f'
]
@@ -216,14 +245,20 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
args.append(self.bundle_path)
p = subprocess.Popen(args,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
if self.config.applehelp_disable_external_tools:
self.info('skipping')
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpCodeSigningFailed(output)
self.warn('you will need to sign this help book with:\n %s'
% (' '.join([pipes.quote(arg) for arg in args])))
else:
self.info('done')
p = subprocess.Popen(args,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
output = p.communicate()[0]
if p.returncode != 0:
raise AppleHelpCodeSigningFailed(output)
else:
self.info('done')

7
sphinx/config.py
View File

@@ -14,6 +14,7 @@ from os import path, environ
import shlex
from six import PY3, iteritems, string_types, binary_type, integer_types
from six.moves.urllib.parse import quote as urlquote
from sphinx.errors import ConfigError
from sphinx.locale import l_
@@ -133,8 +134,7 @@ class Config(object):
# Apple help options
applehelp_bundle_name = (lambda self: make_filename(self.project),
'applehelp'),
applehelp_bundle_id = (lambda self: 'com.mycompany.%s.help' \
% make_filename(self.project), 'applehelp'),
applehelp_bundle_id = (None, 'applehelp'),
applehelp_dev_region = ('en-us', 'applehelp'),
applehelp_bundle_version = ('1', 'applehelp'),
applehelp_icon = (None, 'applehelp'),
@@ -156,6 +156,9 @@ class Config(object):
environ.get('OTHER_CODE_SIGN_FLAGS',
'')),
'applehelp'),
applehelp_indexer_path = ('/usr/bin/hiutil', 'applehelp'),
applehelp_codesign_path = ('/usr/bin/codesign', 'applehelp'),
applehelp_disable_external_tools = (False, None),
# Epub options
epub_basename = (lambda self: make_filename(self.project), None),

2
sphinx/environment.py
View File

@@ -428,7 +428,7 @@ class BuildEnvironment:
config.exclude_patterns[:] +
config.templates_path +
config.html_extra_path +
['**/_sources', '.#*']
['**/_sources', '.#*', '*.lproj/**']
)
self.found_docs = set(get_matching_docs(
self.srcdir, config.source_suffix, exclude_matchers=matchers))

52
sphinx/quickstart.py
View File

@@ -268,58 +268,6 @@ html_static_path = ['%(dot)sstatic']
# Output file base name for HTML help builder.
htmlhelp_basename = '%(project_fn)sdoc'
# -- Options for Apple Help output ----------------------------------------
# The help file title.
#
# This needs to go in the CFBundleHelpBookName field in your application,
# and is displayed in the title bar of the help viewer.
#applehelp_title = u'%(project_str)s Help'
# The name of the bundle.
#applehelp_bundle_name = u'%(project_fn)s'
# The bundle id.
#applehelp_bundle_id = 'com.mycompany.%(project_url)s.help'
# The development region. Should be 'en-us' in most cases.
#applehelp_dev_region = 'en-us'
# The bundle version.
#applehelp_bundle_version = '1'
# The icon file
#applehelp_icon = '%(project_fn)s.png'
# These allow remote searching of a knowledge base on your server
#applehelp_kb_url = "https://kb.example.com/search?p='product'&q='query'&l='lang'"
#applehelp_kb_product = '%(project_fn)s-%(release)s'
# This lets you host a remote copy of the documentation that you can update
# without having to ship new versions of your application
#applehelp_remote_url = 'https://help.example.com/%(project_fn)s/%(version)s/'
# Whether to index anchors
#applehelp_index_anchors = False
# Minimum term length for indexing
#applehelp_min_term_length = None
# Stop words (either a language identifier, for built-in stop words, or a plist)
#applehelp_stopwords = %(language)r
# Locale for indexing
#applehelp_locale = %(language)r
# If you call Sphinx from Xcode, the default settings for code signing
# will apply automatically.
# The code signing identity to use (if None, the bundle is not signed)
#applehelp_codesign_identity = os.environ.get('CODE_SIGN_IDENTITY', None)
# Code signing flags to pass (as a list)
#applehelp_codesign_flags = shlex.split(os.environ.get('OTHER_CODE_SIGN_FLAGS', ''))
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {