Sphinx Contrib QtHelp

2.0.0 verified Tue May 12 auth: no python install: verified

sphinxcontrib-qthelp is a Sphinx extension that generates project files and content suitable for creating QtHelp documents (.qch files) from Sphinx documentation. The current version is 2.0.0, and it is actively maintained with releases as needed to align with Sphinx and Python compatibility.

pip install sphinxcontrib-qthelp

Common errors

error Configuration error: The following configuration values are required by the 'qthelp' builder but are not set: 'qthelp_basename', 'qthelp_title' ↓

cause The mandatory `qthelp_basename` and `qthelp_title` variables have not been defined in your Sphinx `conf.py` file.

fix

Add qthelp_basename = 'MyProject' and qthelp_title = 'My Project Documentation' (and other optional qthelp_ variables as needed) to your conf.py.

error ModuleNotFoundError: No module named 'sphinxcontrib.qthelp' ↓

cause The `sphinxcontrib-qthelp` Python package is either not installed in your active Python environment or its name is misspelled in the `extensions` list in `conf.py`.

fix

Install the package using pip install sphinxcontrib-qthelp and ensure extensions = ['sphinxcontrib.qthelp'] is correctly specified in your conf.py.

error FileNotFoundError: [Errno 2] No such file or directory: 'qcollectiongenerator' ↓

cause The `qcollectiongenerator` command, part of the Qt Help Tools and necessary for compiling `.qch` files, is not installed or not accessible in your system's PATH.

fix

Install the Qt SDK (specifically the Qt Help Tools component) and ensure the directory containing qcollectiongenerator (e.g., C:\Qt\...\bin on Windows or /usr/bin on Linux) is added to your system's PATH environment variable.

Warnings

breaking Version 2.0.0 of sphinxcontrib-qthelp requires Python >= 3.9. Older Python environments will need to use an older version of this package. ↓

fix Ensure your project uses Python 3.9 or newer, or pin sphinxcontrib-qthelp to a compatible older version (e.g., <2.0.0) for older Python environments.

breaking This package, like other `sphinxcontrib` extensions, tracks Sphinx versions closely. Newer versions of `sphinxcontrib-qthelp` (e.g., 2.0.0) may not be compatible with significantly older Sphinx installations (e.g., Sphinx < 5.0), leading to build failures. For older Sphinx setups, you might need to pin `sphinxcontrib-qthelp` to an older version (e.g., 1.0.3). ↓

fix Align the `sphinxcontrib-qthelp` version with your Sphinx installation's compatibility requirements. Refer to the Changelog for specific version notes, or consider upgrading Sphinx if possible.

gotcha Generating the final `.qch` QtHelp file requires the external `qcollectiongenerator` command-line tool. This tool is part of the Qt development tools and is not installed when you `pip install sphinxcontrib-qthelp`. Users must install Qt development packages (e.g., `qt-tools` or similar, depending on OS) separately. ↓

fix Install the necessary Qt development tools for your operating system to ensure `qcollectiongenerator` is available in your PATH.

gotcha Prior to Sphinx 2.0, several `sphinxcontrib` packages (including `qthelp`) were often bundled directly with Sphinx. For Sphinx 2.0 and later, these extensions must be explicitly installed via `pip`. ↓

fix Always explicitly `pip install sphinxcontrib-qthelp` when working with Sphinx versions 2.0 or newer, even if you previously didn't need to.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 18.6M

3.10 alpine (musl) - - 0.00s 18.6M

3.10 slim (glibc) wheel 1.5s 0.00s 19M

3.10 slim (glibc) - - 0.00s 19M

3.11 alpine (musl) wheel - 0.00s 20.4M

3.11 alpine (musl) - - 0.00s 20.4M

3.11 slim (glibc) wheel 1.6s 0.00s 21M

3.11 slim (glibc) - - 0.00s 21M

3.12 alpine (musl) wheel - 0.00s 12.3M

3.12 alpine (musl) - - 0.00s 12.3M

3.12 slim (glibc) wheel 1.4s 0.00s 13M

3.12 slim (glibc) - - 0.00s 13M

3.13 alpine (musl) wheel - 0.00s 12.0M

3.13 alpine (musl) - - 0.00s 11.9M

3.13 slim (glibc) wheel 1.4s 0.00s 13M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 18.1M

3.9 alpine (musl) - - 0.00s 18.1M

3.9 slim (glibc) wheel 1.7s 0.00s 19M

3.9 slim (glibc) - - 0.00s 19M

Imports

sphinxcontrib.qthelp
wrong
```
import sphinxcontrib_qthelp
```
correct
```
extensions = ['sphinxcontrib.qthelp']
```
Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not by direct Python import statements in typical usage.

Quickstart last tested: 2026-04-24

To use sphinxcontrib-qthelp, add 'sphinxcontrib.qthelp' to the 'extensions' list in your Sphinx project's conf.py file. You can also set specific configuration options for the QtHelp builder, such as the basename, namespace, and title of the help file. After configuration, build the documentation using the 'qthelp' builder via the sphinx-build command.

# conf.py

# -- Project information -----------------------------------------------------
project = 'My QtHelp Project'
copyright = '2026, Author Name'
author = 'Author Name'
version = '0.1'
release = '0.1.0'

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.qthelp' # Add this line to enable the extension
]

# -- Options for qthelp output -----------------------------------------------
# For a full list of options, see the Sphinx documentation.
qthelp_basename = 'MyProjectHelp'
qthelp_namespace = 'org.mycompany.myproject.help'
qthelp_title = 'My Project Documentation'

# Example of how to build from command line (after configuring conf.py):
# sphinx-build -b qthelp sourcedir builddir