利用Qt Assistant 定制帮助文档
为了将Qt Assistant定制为自己应用程序的帮助文档浏览器。需要完成以下几步：
一、导入HTML格式的帮助文档
（1）生成HTML文件。首先，针对自己的应用程序创建HTML格式的帮助文档，请参见《Doxygen生成HTML文件》。（下面示例假设HTML文件已经存在）
（2）新建Gui应用。QtCreator-->new Project-->Qt Widgets Application 新建项目名称定义为“MyHelpThis”，类名定义为“MainWindow”，基类保持QMainWindow不变。
（3）添加图标。在项目目录中新建文件夹，命名为“documentation”。在documentation文件夹中再新建一个“images”文件夹，往里面拷贝一个图标图片，以后将作为Assistant程序左上角的图标，此例中使用了lib.png。
（4）添加HTML文件。在documentation文件夹中再新建一个“demoHtml”文件夹，将从步骤（1）生成的HTML文件拷贝至其中。此例中放入已经存在的7个HTML文件。
二、创建.qhp文件，并利用命令生成.qch文件
（1）关于qhp与qch
qhp是Qt Help Project的缩写，qhp类型文件是XML格式的，负责组织实际用到的帮助文件（通常为HTML文件，即需要在Qt Assistant中浏览的文件）。
qch是Qt Compressed Help的缩写，qch类型文件是二进制格式的，qch文件是Qt Assistant能够识别的文档最小单元，可以通过Qt Assistant->编辑->首选项->文档标签页->添加/移除操作来注册或者注销一个qch文件。
也可以通过命令“assistant -register doc.qch”来注册qch文件。注册后，即可在Assistant界面中浏览帮助文档。
两者关系：qhp文件通过qhelpgenerator命令生成压缩的qch文件。命令格式如下：
qhelpgenerator myhelp.qhp -o myhelp.qch
（2）创建qhp文件。在documentation文件夹中创建一个文本文件，命名为“myhelp”，修改文件后缀为qhp，用Notepad++工具打开文件，编辑内容如下：
1 <?xml version="1.0" encoding="GB2312"?> 2 <QtHelpProject version="1.0"> 3 <namespace>bookmisClient.myhelp</namespace> 4 <virtualFolder>doc</virtualFolder> 5 <filterSection> 6 <toc> 7 <section title="首页" ref="./demoHtml/index.html"> 8 <section title="用户登录" ref="./demoHtml/userlogon.html"></section> 9 <section title="书籍查询" ref="./demoHtml/bookquery.html"></section> 10 <section title="续借书籍" ref="./demoHtml/Renewal.html"></section> 11 <section title="系统管理" ref="./demoHtml/systemmanage.html"></section> 12 <section title="日志管理" ref="./demoHtml/log.html"></section> 13 <section title="关于" ref="./demoHtml/about.html"></section> 14 </section> 15 </toc> 16 <keywords> 17 <keyword name = "登录" ref="./demoHtml/userlogon.html"></keyword> 18 <keyword name = "续借" ref="./demoHtml/Renewal.html"></keyword> 19 <keyword name = "日志" ref="./demoHtml/log.html"></keyword> 20 </keywords> 21 <files> 22 <file>demoHtml/*.html</file> 23 <file>image/*.png</file> 24 </files> 25 </filterSection> 26 </QtHelpProject>
（3）解读qhp文件。这个qhp文件是XML格式的。
① 第一行是XML序言，注意这里指定encoding为GB2312，这样是为了使用中文。如果只想使用英文，那么编码一般为UTF-8。
② 第二行指定了QtHelpProject版本为1.0
③ 第三行指定了命名空间namespace，每一个qhp文件的命名空间都必须是唯一的，命名空间会成为Qt Assistant中页面的URL的第一部分。
④ 第四行指定了一个虚拟文件夹virtualFolder，这个文件夹并不需要创建，它是指用来区分文件的。
⑤ 过滤器。下面的过滤器部分filterSection标签包含了目录表、索引和所有文档文件的列表。过滤器部分可以设置过滤器属性，这样以后可以在Qt Assistant中通过过滤器来设置文档是否显示，不过，因为此例只有一个文档，所以不需要Qt Assistant的过滤器功能，这里也就不需要设置过滤器属性。
⑥ 目录表。toc（table of contents）标签中创建了所有HTML文件的目录，指定了它们的标题和对应的路径，此例目录表为：
> 首页
> 用户登录
> 书籍查询
> 续借书籍
> 系统管理
> 日志管理
> 关于
⑦ keywords标签。指定了所有索引的关键字和对应的文件，这些关键字会显示在Qt Assistant的索引页面。
⑧ files标签。Files标签中列出了所有的文件，其中有HTML文件和图片文件。注意：如果有许多的同类型文件，直接可以写为：
<file>文件夹名称/*.文件类型</file>
（4）生成qch文件。
打开命令行控制台，使用cd命令跳转至项目目录的documentation目录下，然后依次输入下面的命令（当然，要保证命令正常运行，需要将Qt安装目录的bin目录路径添加到系统的PATH环境变量中）：
① 命令1：qhelpgenerator myhelp.qhp -o myhelp.qch
此命令作用生成qch文件。
② 命令2：assistant -register myhelp.qch
此命令作用注册qch文件。当注册成功后，会显示“documentation successfully registered”提示框。
③ 命令3：assistant
此命令作用启动Assistant。当然，也可以从开始菜单中启动Qt Assistant。启动后可以在Assistant的内容Tab中目录表的最末尾找到我们的目录表，同时可以发现我们的HTML文档内容。
（5）不过，（4）不是必须的。只是为了测试qhp文件是否正确可用。另外，想象一下，生成一个帮助文档还追随在别人下面多俗呀~~~如果您仅仅为了想验证一下可行性，也可到此为止。否则，请再继续看下面内容。
三、创建.qhcp文件，并利用命令生成.qhc文件
欲使Qt Assistant只显示我们自己的帮助文档？最简单的方法就是生成帮助集合文件即.qhc文件。
（1）关于qhcp与qhc
qhcp是Qt Help Collection Project的缩写，该文件是XML格式的，其主要作用是将qch二进制文件组织成为一个collection，定制客户化的Assistant。
qhc则是由qhcp文件通过qcollectiongenerator命令生成的二进制文件，启动Assistant时需要指定collection参数，即qhc文件。
qhc文件中是qch文件的集合，打开Assistant时，通过指定当前collection即可注册多个帮助文档。
命令格式：qcollectiongenerator myHelp.qhcp -o myHelp.qhc
（2）创建qhcp文件。在documentation文件夹中创建一个文本文件，命名为“myHelp”，修改文件后缀为qhcp，用Notepad++工具打开文件，编辑内容如下：
1 <?xml version="1.0" encoding="GB2312"?> 2 <QHelpCollectionProject version="1.0"> 3 <assistant> 4 <title>图书管理客户端帮助文档</title> 5 <applicationIcon>image/lib.png</applicationIcon> 6 <cacheDirectory>cache/myhelp</cacheDirectory> 7 <homePage>qthelp://bookmisClient.myhelp/doc/index.html</homePage> 8 <startPage>qthelp://bookmisClient.myhelp/doc/index.html</startPage> 9 <aboutMenuText> 10 <text>关于</text> 11 </aboutMenuText> 12 <aboutDialog> 13 <file>./about.txt</file> 14 <icon>image/lib.png</icon> 15 </aboutDialog> 16 <enableDocumentationManager>false</enableDocumentationManager> 17 <enableAddressBar>false</enableAddressBar> 18 <enableFilterFunctionality>false</enableFilterFunctionality> 19 </assistant> 20 <docFiles> 21 <generate> 22 <file> 23 <input>myhelp.qhp</input> 24 <output>myhelp.qch</output> 25 </file> 26 </generate> 27 <register> 28 <file>myhelp.qch</file> 29 </register> 30 </docFiles> 31 </QHelpCollectionProject>
（3）解读qhcp文件。这个qhcp文件也是XML格式的。
① 第一行、第二行同qhp文件解释。
② 第三行起始，assistant标签中是对Qt Assistant的外观和功能的定制。其中设置了标题、图标、缓存目录、主页、起始页、About菜单文本、关于对话框的内容和图标等，还关闭了一些没有用的功能。
③ 第六行缓存目录cacheDirectory，是进行全文检索等操作时缓存文件要存放的位置。
④ 第七、八行主页homePage、起始页startPage。这里使用了第二步中提到的Qt Assistant的页面的URL，这个URL由“qthelp://”开始，然后是在.qhp文件中设置的命名空间，然后是虚拟文件夹，最后是具体的HTML文件名。
⑤ 关闭功能。因为Qt Assistant可以添加或者删除文档来为多个应用程序提供帮助，但此例只是为一个应用程序提供帮助，并且不希望删除我们的文档，所以禁用了文档管理器documentation manager；而且这里的文档集很小，而且只有一个过滤器部分，所以也关闭了地址栏address bar和过滤器功能filter functionality。
⑥ 关于about.txt文件。在documentation目录下新建一个文本文件，命名为“about”，在其中输入此制作的帮助的说明信息，作为Qt Assistant的about菜单的显示内容。
⑦ docFiles标签。此标签其实就是完成了第二步中的所有命令操作，不过与第二步不同的是，第二步是在默认的集合文件中注册的，而这里是在我们自己的集合文件中注册的。
（4）生成.qhc文件。
打开命令行控制台，使用cd命令跳转至项目目录的documentation目录下，然后依次输入下面的命令（当然，要保证命令正常运行，需要将Qt安装目录的bin目录路径添加到系统的PATH环境变量中）：
① 命令1：qcollectiongenerator myhelp.qhcp -o myhelp.qhc
此命令作用生成qhc文件。
② 命令2：assistant -collectionFile myhelp.qhc
此命令作用为了测试我们定制的Assistant。此时在运行Qt Assistant时指定了集合文件为我们自己的qhc文件，所以运行后只仅仅显示我们自己的HTML文档。
现在，可以看到Qt Assistant的图标也更改了，打开帮助菜单中的“关于该帮助”菜单，也可以看到前面添加的about.txt文件的文本内容，效果如下图所示：
四、从程序中启动Qt Assistant查看帮助
（1）添加assistant类。添加新文件—>选择C++ class类，类名为assistant，基类不填写，类型信息选择无。
① assistant.h文件如下（详见注释）：
1 #ifndef ASSISTANT_H 2 #define ASSISTANT_H 3 4 #include <QtCore/QString> 5 6 class QProcess; 7 class Assistant 8 { 9 public: 10 Assistant(); 11 ~Assistant(); 12 void showDocumentation(const QString &file); 13 14 private: 15 bool startAssistant(); 16 17 private: 18 QProcess *proc; 19 }; 20 21 #endif // ASSISTANT_H
② assistant.cpp文件如下（详见注释）：
1 #include <QtCore/QByteArray> 2 #include <QtCore/QProcess> 3 #include <QtWidgets/QMessageBox> 4 #include "assistant.h" 5 6 Assistant::Assistant(): proc(0) 7 { 8 } 9 10 Assistant::~Assistant() 11 { 12 if (proc && proc->state() == QProcess::Running) 13 { 14 // 试图终止进程 15 proc->terminate(); 16 proc->waitForFinished(3000); 17 } 18 // 销毁proc 19 delete proc; 20 } 21 22 // 显示文档 23 void Assistant::showDocumentation(const QString &page) 24 { 25 if (!startAssistant()) 26 return; 27 28 QByteArray ba("SetSource "); 29 ba.append("qthelp://bookmisClient.myhelp/doc/"); 30 proc->write(ba + page.toLocal8Bit() + '\n'); 31 } 32 33 // 启动Qt Assistant 34 bool Assistant::startAssistant() 35 { 36 // 如果没有创建进程，则新创建一个 37 if (!proc) 38 proc = new QProcess(); 39 // 如果进程没有运行，则运行assistant，并添加参数 40 if (proc->state() != QProcess::Running) 41 { 42 QString app = QLatin1String("../MyHelpThis/documentation/assistant.exe"); 43 QStringList args; 44 args << QLatin1String("-collectionFile") 45 << QLatin1String("../MyHelpThis/documentation/myhelp.qhc"); 46 proc->start(app, args); // 相当于执行命令：assistant –collectionFile myHelp.qhc 47 if (!proc->waitForStarted()) 48 { 49 QMessageBox::critical(0, QObject::tr("my help"), 50 QObject::tr("Unable to launch Qt Assistant (%1)").arg(app)); 51 return false; 52 } 53 } 54 return true; 55 }
（2）准备assistant.exe程序。将Qt安装目录的bin目录中的assistant.exe程序复制到项目目录的documentation目录中。
（3）修改mainwindow.cpp文件。修改后具体如下（详见注释）：
1 #include "mainwindow.h" 2 #include "ui_mainwindow.h" 3 #include "assistant.h" 4 5 MainWindow::MainWindow(QWidget *parent) 6 : QMainWindow(parent) 7 , ui(new Ui::MainWindow) 8 , pAssistant(nullptr) 9 { 10 ui->setupUi(this); 11 // 创建命令按钮 12 QAction* pHelp = new QAction("help", this); 13 ui->mainToolBar->addAction(pHelp); 14 // 绑定信号与槽 15 connect(pHelp, SIGNAL(triggered()), this, SLOT(startAssistant())); 16 // 创建Assistant对象 17 pAssistant = new Assistant; 18 } 19 20 MainWindow::~MainWindow() 21 { 22 delete ui; 23 delete pAssistant; 24 } 25 26 void MainWindow::startAssistant() 27 { 28 // 按下“help”按钮，运行Qt Assistant，显示index.html页面 29 pAssistant->showDocumentation("index.html"); 30 }
（4）编译程序（注意工程的文件路径问题）。
（5）工程文件目录如下：
工程文件目录：
documentation文件夹目录：
（6）运行程序。按下工具栏的help按钮，就可以启动并查看帮助文档了。
五、利用批处理启动Qt Assistant查看帮助
利用程序启动Qt Assistant显得比较麻烦点！那么，如何可以快速启动Qt Assistant，不用每次都敲命令呢？我们可以选择使用批处理文件。
在documentation文件夹中新建一个文本文件，命名为“myhelp”,修改文件类型为bat。用Notepad++工具打开文件，编辑内容如下：
1 echo off 2 echo Setting up environment for Qt usage... 3 set PATH=C:\Qt\Qt5.3.2\5.3\msvc2010_opengl\bin;%PATH% 4 cd /D C:\Qt\Qt5.3.2\5.3\msvc2010_opengl 5 cd /D F:\qtHelpDemoDoc\MyHelpThis\documentation 6 qhelpgenerator myhelp.qhp -o myhelp.qch 7 qcollectiongenerator myhelp.qhcp -o myhelp.qhc 8 assistant -collectionFile myhelp.qhc 9 echo Remember to call vcvarsall.bat to complete environment setup!
然后，双击bat文件执行。可以看到四（6）中按下help按钮同样的效果图。
六、实现过程中可能遇到的问题
（1）在qhp文件中，设置ref错误，导致跳转不符合预期。
（2）在qhp文件中，设置html文件路径错误，导致无法正常显示相应内容。
注意 系统环境：Windows7 + Qt5.3.2 + QtCreator3.2.1
