db2qthelp — a DocBook book to QtHelp project converter
db2qthelp converts a DocBook book to a QtHelp project.
db2qthelp is in an early stage of “development”. It works well for me but it may work with my setup only.
Any feedback is appreciated.
I usually write my user documentation using DocBook. For my recent applications built on top of Qt, I needed something that generates in-app help pages. db2qthelp does this.
The current version is db2qthelp-0.2.
You may install db2qthelp using
python -m pip install db2qthelp
You may download a copy or fork the code at db2qthelp's github page.
Besides, you may download the current release here:
db2qthelp is licensed under the BSD license.
db2qthelp is implemented in Python. It is started on the command line.
db2qthelp requires some prerequisites. In the following, the steps for a QtHelp from a DocBook book are described.
You should have a user documentation written as a DocBook book. Images should be stored in a subfolder, at best one that is located in the same folder as the DocBook document itself. E.g. if you have a project, you may have a folder “docs” in which the document itself (“docs/userdocs.xml”) is located and the images / figures it references are located in “docs/images/*”.
In the first step, you have to convert this document to a single-HTML document. Being in the docs folder, I use xsltproc for this using a call similar to this one:
xsltproc.exe --output userdocs.html single_html.xsl userdocs.xml
Here, “single_html.xsl” is a slightly modified DocBook style sheet. You may find it in this package under “data/single_html.xsl”. Please not that you have to update the references to your docbook stylesheets location.
What we get is a HTML-representation of the DocBook user docs named “userdocs.html”.
We now need a template for our QtHelp project. Generate it using db2qthelp by calling:
python db2qthelp --generate
You will get a file named “template.qhp”. It should be located in the same folder as your DocBook document. You may though name it differently to set it's name on generation use:
python db2qthelp --generate --template new_template_name.qhp
Open it in an editor. It should look like this:
<?xml version="1.0" encoding="latin1"?>
<QtHelpProject version="1.0">
<namespace>%source%</namespace>
<virtualFolder>doc</virtualFolder>
<filterSection>
<filterAttribute>%appname%</filterAttribute>
<toc>
%toc%
</toc>
<keywords>
%keywords%
</keywords>
<files>
<file>*.html</file>
<file>*.png</file>
<file>*.gif</file>
</files>
</filterSection>
</QtHelpProject>
You may note that there are some placeholders. Both will be later on filled by db2qthelp
- %source% is the complete URL to your documentation, it usually looks like “org.foo.bar.MyFancyApp_v0.1”
- %appname% is your application name (e.g. “MyFancyApp”)
- %toc% will be replaced by the documentation's structure (table of contents)
- %keywords% will be replaced by the collected keywords
You may add additional filter attributes.
Well, that's almost everything. Run db2qthelp again to build the documentation:
python db2qthelp -i userdocs.html -t new_template_name.qhp -s org.foo.bar.MyFancyApp_v0.1 -a MyFancyApp -p c:\Qt\bin
The options tell db2qthelp to read the HTML document “userdocs.html” generated from our original DocBook book, to use our project template “new_template_name.qhp” and that images and figures are located in “images”.
As we did not define the destination folder, db2qthelp uses the default “qtdocs”.
The built documentation can be found in the destination folder. You need two files to include it in your application:
- <APPLICATION_NAME>.qch
- <APPLICATION_NAME>.qhc
The script has the following options:
- --input/-i <DOCBOOK_HTML>: Defines the DocBook HTML document to parse
- --appname/-a <APPLICATION_NAME>: Sets the name of the application
- --source/-s <ADDITIONAL_FILES_FOLDER>: Sets the documentation source url
- --files/-f <ADDITIONAL_FILES_FOLDER>[,<ADDITIONAL_FILES_FOLDER>]*: Sets the folder(s) to collect files from
- --destination/-d <DESTINATION_FOLDER>: Sets the output folder
- --template/-t <TEMPLATE_FILE>: Defines the QtHelp project template to use; default: ‘template.qhp’
- --generate/-g: If set, the template is written to the file as defined by --template; The application quits afterwards
- --path/-p <QT_PATH>: Sets the path to the Qt binaries to use
- --help: Prints the help screen
db2qthelp copies *.png and *.gif-files from the folders defined using --files, first.
It then reads the HTML-file generated from DocBook defined using --input and processes it. Processing means here that the file is split at sections and appendices. Each subpart is written into the destination folder defined using --destination and included in the table of contents (toc). The paths to references images as defined using --files are replaced by the destination path defined using --destination. In addition, the headers are included in the list of keywords.
Then, the qhp-templated defined using --template is loaded and the placeholders (see above) are replaced by the given / collected data.
db2qthelp generates a qhcp file afterwards as “<DESTINATION_FOLDER>/<APPLICATION_NAME>.qhcp”.
Finally, the script calls two QtHelp processing applications which must be located in the folder defined using --path:
<QT_PATH>/qhelpgenerator <APPLICATION_NAME>.qhp -o <APPLICATION_NAME>.qch
<QT_PATH>/qcollectiongenerator <APPLICATION_NAME>.qhcp -o <APPLICATION_NAME>.qhc
python db2qthelp --generate
Generates the project template file “template.qhp”.
python db2qthelp -i userdocs.html -t template.qhp -s org.foo.bar.MyFancyApp_v0.1 --path c:\Qt\bin
Reads the HTML document “userdocs.html” and the project template “template.qhp” and converts the HTML document to QtHelp assuming images etc. being located in “images”. The Qt binaries are assumed to be found in “c:\Qt\bin”.
- The complete documentation is located at:
- 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
- PaletteWB — a sophisticated palette editor for MS Windows.
- Initial checkin
- Adding configuration options
- Adding a documentation
- Adding first tests
Well, have fun. If you have any comments / ideas / issues, please submit them to db2qthelp's issue tracker on github.