sphinxcontrib-applehelp

sphinxcontrib-applehelp is an official Sphinx extension that adds a new applehelp builder to the Sphinx documentation toolchain, producing .help bundles that macOS recognizes as native Apple Help Books. It reuses Sphinx’s standalone HTML builder as a base and layers on the platform-specific packaging Apple Help requires: an Info.plist manifest, a .lproj localized resources directory, an access page, and a search.helpindex file generated by Apple’s hiutil CLI tool.

The extension exists to remove the manual, error-prone steps of assembling an Apple Help bundle by hand from a set of HTML pages. Instead, a documentation author configures a handful of applehelp_* settings in conf.py (bundle ID, bundle name, icon, locale, remote/KB URLs) and runs sphinx-build -b applehelp, and Sphinx does the rest — including, optionally, invoking codesign to sign the resulting bundle for distribution inside a macOS application.

It was originally part of the core Sphinx codebase and was split out into its own sphinxcontrib package, following the project’s practice of keeping platform- and format-specific builders (LaTeX, man pages, Qt Help, Apple Help, etc.) as separate installable extensions rather than bloating Sphinx’s core.

What You Get

• A new -b applehelp Sphinx build target that outputs a .help bundle instead of plain HTML
• Automatic generation of the Info.plist manifest macOS requires to register the help book (bundle ID, version, title, icon path, KB/remote URLs)
• Help index generation via Apple’s hiutil indexer so the bundle is searchable in the macOS Help viewer
• Optional code signing of the finished bundle via codesign, driven by applehelp_codesign_identity / CODE_SIGN_IDENTITY
• Localized resource copying from a per-locale .lproj source directory into the built bundle
• A applehelp_disable_external_tools escape hatch that skips invoking hiutil/codesign directly and instead prints the exact commands to run manually (useful for building outside of macOS, e.g. in CI)

Common Use Cases

• macOS app help menus - a Mac app developer writes their user guide once in reStructuredText and builds it as the app’s native Help Book via sphinx-build -b applehelp.
• CI-driven Help Book packaging - a build pipeline runs the applehelp builder on a non-Mac runner with applehelp_disable_external_tools enabled, then finishes indexing/signing on a macOS signing machine using the printed commands.
• Multi-format doc pipelines - a project already using Sphinx for web docs (HTML) and PDF (LaTeX) adds Apple Help as a third output target without maintaining a separate doc source.
• Distributing signed help content - an app vendor uses the applehelp_codesign_identity config to produce a help bundle signed with their Developer ID, satisfying macOS Gatekeeper requirements.

Under The Hood

Architecture The entire extension lives in a single module, sphinxcontrib/applehelp/__init__.py, centered on AppleHelpBuilder, a subclass of Sphinx’s StandaloneHTMLBuilder. It overrides init() to redirect the builder’s output directory into the eventual .help bundle’s Contents/Resources/<locale>.lproj path, then overrides handle_finish() to hook two additional finish tasks onto Sphinx’s build pipeline: copy_localized_files and build_helpbook. build_helpbook is the orchestration point — it sequentially writes Info.plist, copies the icon, renders the access page from a template, invokes hiutil to build the search index, and conditionally shells out to codesign. Because it inherits from StandaloneHTMLBuilder, all of Sphinx’s normal HTML rendering (themes, cross-references, TOC) runs unmodified; the extension only adds packaging behavior on top, which keeps the surface area small and the failure modes localized to external-tool invocation.

Tech Stack The package is pure Python 3.9+ with zero runtime dependencies (Sphinx is deliberately not declared as a hard dependency, to avoid a circular-dependency problem noted in the 1.0.8 changelog) and is built with Flit as its packaging backend. It relies entirely on the Python standard library at runtime — plistlib to emit Info.plist, subprocess to call the macOS-only hiutil and codesign binaries, and shlex/pathlib for command construction and path handling. Optional extras split test (pytest), lint (Ruff pinned to an exact version, mypy, types-docutils), and standalone (Sphinx itself, for anyone using the package outside Sphinx’s own build).

Code Quality The project has a small but focused pytest suite (tests/test_applehelp.py) that runs a real Sphinx build against a minimal test root and asserts on the resulting bundle structure, Info.plist contents, and localized-file placement — a practical integration test rather than unit tests of individual methods. Type checking is strict: mypy runs with disallow_untyped_defs, disallow_any_generics, no_implicit_reexport, and several extra error codes enabled, and the package ships a py.typed marker. Linting is handled by a pinned Ruff version with a wide rule selection (bugbear, simplify, pyupgrade, isort, and more). GitHub Actions runs the release workflow via PyPI trusted publishing (OIDC), and a separate workflow keeps translation files in sync via Transifex.

What Makes It Unique Its niche is narrow by design: it is the canonical, Sphinx-team-maintained way to produce Apple’s proprietary Help Book format from a documentation source that would otherwise only produce HTML/PDF/man pages. Rather than reimplementing a documentation generator, it delegates all content rendering to Sphinx’s existing HTML builder and focuses entirely on the macOS-specific packaging contract (bundle layout, hiutil indexing, code signing) — a thin, single-purpose adapter rather than a general-purpose tool.