qdoc使用说明及qch帮助文档的生成
一、介绍什么是qdoc
Qdoc是开发者用于在软件工程中生成文档的一个工具。它从工程的源文件中提取qdoc类型注释，并以html页面或者DITA XML文档的形式格式化到文件中。Qdoc在.cpp和.qdoc文件中查找注释，而不会在.h文件中查找。一条qdoc注释往往以一个前置声明符号（!）开始。
二、使用qdoc的好处和缺点
优点：
a) 通过qdoc自动提取注释生成开发文档。
b) 在对外接口中可直接通过qdoc生成文档做接口文件，不用单独再写文档。
c) 将代码逻辑写到注释中，便于修改代码时修改。避免了之前单独出代码文档时修改代码忘记更新文档，造成文档代码不一致。
d) 支持多种格式输出，qch，html等格式，便于不同阅读方式。
缺点：
a) 必须按照qdoc的格式编写注释，并且注释必须与代码一致。
b) Qdoc不能生成对私有函数注释输出（可通过修改源代码输出）。
c) 使用人数较少，网上文档较少，一般只能看官方文档。
三、创建Qdoc工程
1、 创建qoc的工程
添加空的qt工程，只需要pro文件，用于管理生成qch。
#------------------------------------------------- # # Project created by QtCreator 2016-12-23 T15:22:06 # 备注： 对整个工程生成qch文件 #------------------------------------------------- #创建一个Makefile，不构建任何东西。 TEMPLATE = aux include(doc.pri) # 生成qch文件需要添加此行 PRE_TARGETDEPS += qch_docs
说明
TEMPLATE = aux：用于设置当前工程不调用编译器来创建目标，仅使用makefile生成器。
PRE_TARGETDEPS += qch_docs：设置当前工程依赖qch_docs
2、添加qdoc的目录结构
Qdoc工程目录结构仿照官方qdoc目录进行生成.如图1.
图1
config:存放doc工程的配置文件，很重要。Qdoc的基础配置文件必须放到此目录下，否则会导致生成的qch文件中一堆的没用的链接。如图2。Image文件夹和style文件夹存放一些引用的图片和html样式。后面会用到。
图2
global:全局的配置文件，存放全局qdocconf文件，如一些格式的，源文件编码，生成文档编码，宏定义，源文件后缀配置等。这里面会有一个template目录，用于存放 引用的图片和html样式。可到qt源码下拷贝过来。如图3。
图3
html:生成的html文件目录，qmake以后生成html文件。通过浏览器可直接打开查看文档。如图4。
图4
Images :图片文件路径，文档中可引入图片，所以此目录存放图片。
Src：很重要，用于添加自定义的一些qdoc文件，用于生成doc中的模块文档，对某个模块的单独说明可添加独立的qdoc文件，进行详细描述，不用添加到代码中。此目录文件在qmake的时候会遍历每个qdoc文件进行添加。Index.qdoc很重要，用于添加主页的信息的。如图5.
图5
pri文件在3中介绍。
3、添加qdoc的必须配置文件
① pri文件：用于添加各种设置，如qdoc的输出路径，执行命令等。可参看assistant中qmake Manual章节。
#include($$_PRO_FILE_PWD_/target.pri)
TargetName=doc
HELPGENERATOR = $$shell_path($$[QT_INSTALL_BINS]/qhelpgenerator) #-platform minimal
QDOC_BIN = $$shell_path($$[QT_INSTALL_BINS]/qdoc)
QDOC_PREPARE = $$QDOC_BIN -prepare
QDOC_GENERATE = $$QDOC_BIN -generate
QDOC_GLOBAL = QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS]/src
QDOC_INDEX_DIR=$$[QT_INSTALL_DOCS]
#COMPAT =
defineReplace(cmdEnv) {
!equals(QMAKE_DIR_SEP, /): 1 ~= s,^(.*)$,(set \\1) &&,g
return("$$1")
}
defineReplace(qdoc) {
return("$$cmdEnv(SRCDIR=$$_PRO_FILE_PWD_../ OUTDIR=$$1 $$QDOC_GLOBAL) $$QDOC_BIN")
}
PROJECT_PWD=$$PWD/../
message($$PROJECT_PWD)
QHP_FILE = $$PROJECT_PWD/doc/html/$${TargetName}.qhp
QCH_FILE = $$PROJECT_PWD/$${TargetName}.qch
doc_generate.TARGET = $$TargetName.qhp
doc_generate.commands = $$QDOC_PREPARE $$PWD/config/$${TargetName}.qdocconf -outputdir $$PROJECT_PWD/doc/html \
$$escape_expand(\n\t) $$QDOC_GENERATE $$PWD/config/$${TargetName}.qdocconf -outputdir $$PROJECT_PWD/doc/html
qch_docs.TARGET=$$TargetName.qch
qch_docs.commands = $$HELPGENERATOR -o $$QCH_FILE $$QHP_FILE
qch_docs.depends += doc_generate
QMAKE_EXTRA_TARGETS += doc_generate qch_docs
win32 {
system(copy /y $$QCH_FILE $$PROJECT_PWD/)
}
② qdocconf文件：为了生成文档，QDoc使用带有qdocconf扩展名的配置文件来存储配置设置.主要配置项目名称，输入输出路径，宏，版本号等信息。config目录下的doc.qdocconf.主要是针对当前工程进行设置的，global下的主要是通用的。
#自定义conf文件， 这里使用的是Qt提供的。
include(../global/qt-module-defaults-offline.qdocconf)
#此文件里面写了编码的格式，所以需要修改此里面的编码才有效
include(../global/fileextensions.qdocconf)
#此文件配置输出的html格式
include(../global/qt-html-templates-offline.qdocconf)
#项目
#project = doc
#项目名称
description = doc项目
#版本号
version = 1.0
#Qt 版本号， 可以定义自己的版本号，这是是为了使用以下Qt提供的conf文件
QT_VER=1.0
#所依赖的模块
depends += \
qtcore \
qtnetwork \
qtwidgets \
qmake \
xml
#头文件路径
headerdirs +=.. \
../src \
../../doc \
#源代码路径
sourcedirs = .. \
../src \
../../doc \
outputformats=HTML
#工程整体信息， 包括文件名、工程名、注册时的名称空间
qhp.projects = doc
qhp.doc.file = doc.qhp
qhp.doc.namespace = com.doc.1.0
#在Qt assistant 内容tab页的展示信息
qhp.doc.virtualFolder = doc
qhp.doc.indexTitle = doc项目
#qhp.doc.indexRoot =
qhp.doc.subprojects = classes
qhp.doc.subprojects.classes.title = C++ Classes
qhp.doc.subprojects.classes.indexTitle = C++ Classes
qhp.doc.subprojects.classes.selectors = class fake:headerfile
qhp.doc.subprojects.classes.sortPages = true
#unknown
qhp.doc.filterAttributes = doc
qhp.doc.customFilters.doc.name = doc111111
qhp.doc.customFilters.doc.filterAttributes = doc222222
#首页 此处使用的是title 用的是index.qdoc中的title，不使用title无法正常连接
navigation.homepage = "doc Project"
#navigation.landingpage = "doc"
navigation.cppclassespage = "C++ Classes"
#输出路径， 注意在include 的conf文件中， 可能定义路径， 因此这里使用相对路径， 未必指向“当前路径”。
outputdir = ../html
#图片路径
imagedirs = ../images
#需要的图片
#HTML.extraimages += image/111.jpg
#把图片编译到 qhp文件中
#qhp.extraFiles += image/111.jpg
#tag文件，必需
tagfile = ../doc.tags
4、添加一些基本的qdoc文件，用于进行添加页面，添加模块说明或模块划分
Qdoc文件主要用于添加一些说明文档，添加新页面，如某个模块的独立说明，或者需要在qdoc中列出所有的方法，所有的类，或自己指定的需要输出的列表等，都可在src目录下添加qdoc文件。此处需要重点说明的是，需要添加index.qdoc文件，此文件中需要添加index.html的页面，用于根节点的显示如下：
/*! \page index.html \keyword doc Reference Documentation \title doc project 介绍项目XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX */
5、生成qch/html文件
添加完基础文件和配置文件，即可生成qch文件了，在pro项目上右键，qmake，即可生成对应的qch文件。
6、使用qch文件
1、 直接打开html目录，查看。
2、 通过assistant导入使用。参见：使用qch文件。http://www.cnblogs.com/ll965452300/p/6721493.html
四、踩过的坑
1、编码问题：因为qdoc支持设置源码的编码和输出文档的编码，global/fileextensions.qdocconf中会有三个编码设置：
Naturallanguage：qdoc生成的文档使用的自然语言。包含汉子的话一般改为zh-Hans。默认为en。
Outputencoding：由qdoc生成的文档的编码。即src目录下那些文件输出的文档编码。UTF-8即可。
Sourceencoding：源代码和文档的编码。此处就是一大坑，如果qt creater中设置的gbk，此处一定要设置为GBK,如果是UTF-8那也要设置一样，并且源码文档一定要保持一个编码，否则怎么修改都会导致生成文档出现乱码。有时候出现qmake的时候报错也可能是编码问题导致。
2、assistant中doc节点为空：需要在doc.qdocconf中添加navigation.homepage = "doc Project"，并且需要在index.qdoc中的title也写为“doc Project”，因为在查找的时候使用的是title去连接的，所以必须修改为一致。
五、注意事项-wsj
1、编译过程中如果遇到类似下列错误
error: Environment variable 'QT_INSTALL_DOCS' undefined
则可以直接在该项目中添加环境变量即可，如下所示
通过创建mydoc.pri mydoc.pro 工程编译后回生成html目录
最后生成qch文件
2.使用
将qch文件和doc文件夹（修改为qtmqtt）复制到qt安装目录的相关docs下C:\Qt\Qt5.9.8\Docs\Qt-5.9.8
然后qtcreator添加qch即可。后续直接可以F1调用qtmqtt相关类的帮助文档
参考自：https://www.cnblogs.com/ll965452300/p/6720545.html
http://t.zoukankan.com/aslistener-p-4775114.html
