Sphinx Contrib QtHelp

2.0.0 · active · verified Sun Mar 29

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.

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

pip install sphinxcontrib-qthelp Install latest version

Imports

sphinxcontrib.qthelp
```
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

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

view raw JSON →