Apple Help Book generation #1675

Merged
merged 15 commits into from Mar 8, 2015

Projects

None yet

2 participants

@al45tair
Contributor

This pull request adds support for generating Apple Help Books to Sphinx.

@birkenfeld birkenfeld commented on the diff Jan 15, 2015
doc/config.rst
@@ -899,6 +899,139 @@ that use Sphinx's HTMLWriter class.
Output file base name for HTML help builder. Default is ``'pydoc'``.
+.. _applehelp-options:
+
+Options for Apple Help output
+-----------------------------
+
@birkenfeld
birkenfeld Jan 15, 2015 Member

The section should get a versionadded for 1.3.

@birkenfeld birkenfeld and 1 other commented on an outdated diff Jan 15, 2015
doc/builders.rst
@@ -76,6 +76,22 @@ The builder's "name" must be given to the **-b** command-line option of
.. _Qt help: http://qt-project.org/doc/qt-4.8/qthelp-framework.html
+.. module:: sphinx.builders.applehelp
+.. class:: AppleHelpBuilder
+
+ 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
@birkenfeld
birkenfeld Jan 15, 2015 Member

E.g. for the Windows HTML help builder, we have omitted calling the "help compiler" from Sphinx and added that to the instructions of things to do. That way, people can use it somewhere else or use a non-standard (i.e. Wine) installation. Would it make sense to do a similar thing here?

At least for testing, the builder should be able to run all but the "run external programs" steps on all platforms.

@al45tair
al45tair Jan 15, 2015 Contributor

The reason I opted to call them directly is that building an Apple Help bundle is mostly just a case of assembling the collection of files in the right places, then running the indexer to add a help index (and optionally, code-signing). This is in contrast to e.g. the situation with Windows HTML Help, where the files need to be assembled as a help project and then processed by the help compiler to make a special archive file. I think it makes more sense for Sphinx to be able to complete all the necessary steps, since there isn't a special tool that does so.

That said, you’re right that it would be good to have some support for either using a different hiutil in a different path, or not generating the index at all and leaving it for later.

@birkenfeld birkenfeld and 1 other commented on an outdated diff Jan 15, 2015
sphinx/quickstart.py
@@ -266,6 +268,58 @@
# Output file base name for HTML help builder.
htmlhelp_basename = '%(project_fn)sdoc'
+# -- Options for Apple Help output ----------------------------------------
@birkenfeld
birkenfeld Jan 15, 2015 Member

We haven't added potential options for other "minor" builders to the quickstart config, such as devhelp or qthelp, to keep the length from exploding. Since your config values have reasonable defaults, I would prefer that here too.

@al45tair
al45tair Jan 15, 2015 Contributor

OK. I'll remove those. I'm also going to remove the default for applehelp_bundle_id because I think on reflection, if it isn't present in the quick start output, people won't set it and we’ll end up with bad bundle IDs in shipping help files.

@birkenfeld
Member

Thanks for the PR! The new builder isn't tested at all - the minimum amount I'd like to have is to build the test project with it.

See tests/test_build.py:test_build_all.

@al45tair
Contributor

OK, I’ve added configuration variables to let users pick an alternate hiutil or codesign executable, or to disable external tool use altogether. I also added some tests, and fixed a couple of Python 3 issues I spotted. Finally, I’ve added support for <lang>.lproj folders in the source directory, which are ignored by the other builders but when you use the apple help builder will be merged with the output (this is to handle things like InfoPlist.strings, which isn’t dealt with via the existing Sphinx localisation system).

@birkenfeld birkenfeld added this to the 1.3 milestone Jan 21, 2015
@birkenfeld
Member

From a cursory review, this looks good now! I'll merge it for 1.3. Thanks for the contribution!

@birkenfeld birkenfeld merged commit cc58f0a into sphinx-doc:master Mar 8, 2015

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment