sphinxcontrib-qthelp

sphinxcontrib-qthelp is a Sphinx extension that adds a QtHelp output builder, turning your reStructuredText or Markdown documentation into the .qhp and .qch files consumed by Qt Assistant and Qt-based help systems. It packages your docs, index, and table of contents into the QtHelp project format.

Maintained by the core Sphinx team, it is the standard way to ship offline, searchable help content for desktop applications built with Qt.

What You Get

• A Sphinx builder that outputs QtHelp .qhp project files and namespace metadata
• Automatic generation of a keyword index and table of contents for Qt Assistant
• Seamless integration with the standard sphinx-build command via the qthelp target
• A maintained dependency backed by the core Sphinx team

Common Use Cases

• Shipping offline, searchable help for Qt desktop applications
• Generating .qhp and .qch bundles from existing Sphinx documentation
• Providing integrated in-app help viewable in Qt Assistant

Under The Hood

Architecture

The package provides a QtHelpBuilder within the sphinxcontrib namespace that subclasses Sphinx’s StandaloneHTMLBuilder. During the build it renders HTML pages and then emits the QtHelp project (.qhp) descriptor, keyword index, and TOC using Jinja templates shipped with the extension. It hooks into Sphinx through setup(app) which registers the builder and its configuration values.

Tech Stack

Pure Python against the Sphinx builder API, packaged with pyproject.toml. It depends on Sphinx and uses Jinja2 templates (bundled with Sphinx) to render the QtHelp project files. Multi-version testing is configured through tox, and translations are managed via Babel message catalogs.

Code Quality

A compact, single-purpose codebase with a dedicated test module (tests/test_qthelp.py) that validates generated output. It adheres to Sphinx project conventions with type annotations and template-driven rendering, keeping logic readable and the defect surface small.

API Design

Usage is declarative: add the extension to conf.py and invoke sphinx-build with the qthelp builder. A couple of qthelp_* configuration values let you set the namespace and folder, but no imperative coding is required, making it approachable for any existing Sphinx user.