db2qthelp — a DocBook book to QtHelp project converter

Introduction

db2qthelp converts a DocBook book to a QtHelp project. It is written in Python and started on the command line.

db2qthelp is in an early stage of development. It works well for me but it may work with my setup only. I try to make it usable nonetheless, so let me know if something does not work. Thanks.

Usage

Given that your xsltproc together with your DocBook look-up paths are set up and that the Qt applications needed to build Qt Help files are in your executable path, you may convert your DocBook book into Qt Help files like this:

db2qthelp.py -i userdocs.xml

That's all 😃. You'll get a .qch and a .qhc file you may use directly in your Qt Help widget…

Options

The script has the following options:

• --config <FILE> / -c <FILE>: Reads the named configuration file
• --input <INPUT> / -i <INPUT>: Defines the DocBook HTML document to parse
• **--destination <DESTINATION> / -d <DESTINATION>: Sets the output folder
• --appname <APPNAME> / -a <APPNAME>: Sets the name of the application
• --css-definition <CSS_DEFINITION>: Defines the CSS definition file to use
• --generate-css-definition: If set, a CSS definition file is generated
• --qhp-template <QHP_TEMPLATE>: Defines the QtHelp project (.qhp) template to use
• --generate-qhp-template: If set, a QtHelp project (.qhp) template is generated
• --qt-path <QT_PATH> / -Q <QT_PATH>: Sets the path to the Qt binaries
• --xslt-path <XSLT_PATH> / -X <XSLT_PATH>: Sets the path to xsltproc
• --help / -h: show this help message and exit
• --version: show program's version number and exit

Examples

db2qthelp -i userdocs.xml

Generates Qt Help files by processing the DocBook book userdocs.xml. The default CSS style sheets will applied, the used binaries are assumed to be in the path.

db2qthelp -i userdocs/ --css-definition my_style.css

Will collect the HTML files located in the folder userdocs, apply the CSS located in my_style.css, and build the Qt Help files from all files found in the given folder.

Documentation

• The complete documentation is located at https://db2qthelp.readthedocs.io/en/latest/
• The github repository is located at: https://github.com/dkrajzew/db2qthelp
• Discussions are open at https://github.com/dkrajzew/db2qthelp/discussions
• The issue tracker is located at: https://github.com/dkrajzew/db2qthelp/issues
• The PyPI page is located at: https://pypi.org/project/db2qthelp/
• The code documentation (pydoc) is located at: http://www.krajzewicz.de/docs/db2qthelp.html

Installation

The current version is 0.4.0. You may install the latest release using pip:

python -m pip install db2qthelp

Or download the latest release from github. You may as well clone or download the db2qthelp git repository. There is also a page about installing db2qthelp which lists further options.

License

db2qthelp is licensed under the GPLv3 license.

Examples / Users

db2qthelp was used to generate the in-app help for the following applications:

• PaletteWB, an MS Windows application for editing color palettes;
• ShaderWB, an MS Windows application for developing GLSL shaders.

ChangeLog

db2qthelp-0.4.0 (24.08.2025)

• code
  • added support for direct processing of DocBook books
  • added suport for processing chuncked xsltproc HTML output
  • moved to argparse / configparser
  • refactoring
• deployment
  • added installation as a directly callable console script
• tests
  • added coveralls integration ()
  • improved tests ()
• docs
  • reworked documentation
  • added automatic readthedocs docs building ()
• moved to GPLv3

db2qthelp-0.2 (07.01.2023)

• Initial checkin
• Adding configuration options
• Adding a documentation
• Adding first tests

Summary

Well, have fun. If you have any comments / ideas / issues, please submit them to db2qthelp's issue tracker on github.