New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Apple Help Book generation #1675

Merged
merged 15 commits into from Mar 8, 2015

Conversation

Projects
None yet
2 participants
@al45tair
Copy link
Contributor

al45tair commented Jan 14, 2015

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


Options for Apple Help output
-----------------------------

This comment has been minimized.

@birkenfeld

birkenfeld Jan 15, 2015

Member

The section should get a versionadded for 1.3.

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

This comment has been minimized.

@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.

This comment has been minimized.

@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.

@@ -266,6 +268,58 @@
# Output file base name for HTML help builder.
htmlhelp_basename = '%(project_fn)sdoc'
# -- Options for Apple Help output ----------------------------------------

This comment has been minimized.

@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.

This comment has been minimized.

@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

This comment has been minimized.

Copy link
Member

birkenfeld commented Jan 15, 2015

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 added some commits Jan 15, 2015

Added some additional configuration variables for Apple Help.
Removed Apple Help from quickstart conf.py.
Added support for .lproj directories with pre-localised files for Apple Help.
@al45tair

This comment has been minimized.

Copy link
Contributor

al45tair commented Jan 15, 2015

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

This comment has been minimized.

Copy link
Member

birkenfeld commented Jan 21, 2015

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

@birkenfeld birkenfeld force-pushed the sphinx-doc:master branch from b0de517 to cc87d8a Feb 8, 2015

@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