{"id":954,"library":"sphinxcontrib-qthelp","title":"Sphinx Contrib QtHelp","description":"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.","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinxcontrib-qthelp/","tags":["documentation","sphinx","qthelp","qt"],"install":[{"cmd":"pip install sphinxcontrib-qthelp","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false}],"imports":[{"note":"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.","wrong":"import sphinxcontrib_qthelp","symbol":"sphinxcontrib.qthelp","correct":"extensions = ['sphinxcontrib.qthelp']"}],"quickstart":{"code":"# conf.py\n\n# -- Project information -----------------------------------------------------\nproject = 'My QtHelp Project'\ncopyright = '2026, Author Name'\nauthor = 'Author Name'\nversion = '0.1'\nrelease = '0.1.0'\n\n# -- General configuration ---------------------------------------------------\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinxcontrib.qthelp' # Add this line to enable the extension\n]\n\n# -- Options for qthelp output -----------------------------------------------\n# For a full list of options, see the Sphinx documentation.\nqthelp_basename = 'MyProjectHelp'\nqthelp_namespace = 'org.mycompany.myproject.help'\nqthelp_title = 'My Project Documentation'\n\n# Example of how to build from command line (after configuring conf.py):\n# sphinx-build -b qthelp sourcedir builddir","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 2.0.0 of sphinxcontrib-qthelp requires Python >= 3.9. Older Python environments will need to use an older version of this package.","severity":"breaking","affected_versions":"2.0.0 and later"},{"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.","message":"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).","severity":"breaking","affected_versions":"All versions, depending on Sphinx compatibility"},{"fix":"Install the necessary Qt development tools for your operating system to ensure `qcollectiongenerator` is available in your PATH.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly `pip install sphinxcontrib-qthelp` when working with Sphinx versions 2.0 or newer, even if you previously didn't need to.","message":"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`.","severity":"gotcha","affected_versions":"Sphinx 2.0 and later"}],"env_vars":null,"search_vec":"'2.0.0':31 'activ':35 'align':42 'compat':47 'content':16 'contrib':2 'creat':19 'current':28 'document':21,26,48 'extens':10 'file':14,23 'generat':12 'maintain':36 'need':40 'project':13 'python':46 'qch':22 'qt':51 'qthelp':3,6,20,50 'releas':38 'sphinx':1,9,25,44,49 'sphinxcontrib':5 'sphinxcontrib-qthelp':4 'suitabl':17 'version':29","created_at":"2026-03-29T06:09:18.999675+00:00","updated_at":"2026-04-16T22:07:12.394344+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.sphinx-doc.org/","github":"https://github.com/sphinx-doc/sphinxcontrib-qthelp","docs":null,"changelog":"https://github.com/sphinx-doc/sphinxcontrib-qthelp/blob/master/CHANGES.rst","pypi":"https://pypi.org/project/sphinxcontrib-qthelp/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":[],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":"verified"}}