Qt文档系统分析(三)

http://hi.baidu.com/cyclone/blog/item/fa0185350681671f90ef39aa.html

在Qt文档系统分析(一) 我们举了使用一个qdoc3的小例子，在Qt文档系统分析(二) 我们对这个例子进行了简单的分析。但有些内容尽管我们提到了，但没做介绍：

• xxx.index 文件是做什么用的?
• 如何为所有的html文件添加统一的头和尾?

这是两个比较重要的东西，本文就主要介绍它们了。

重新贴出前面用的 xxx.qdocconf 文件(不影响理解的前提下此处加了一个url)：

project = First 

description = First QDoc Exmaple 

url = http://www.firstqdocexample.com/0.1.0 

outputdir = html 

headerdirs = . 

sourcedirs = .

xxx.index

文件生成

前面提到 project、description及url是为了生成的 xxx.index 的服务的，而这个index我们自己是用不到的。那么它有什么用呢？

• project 指定了 xxx.index 文件的名字（即生成 first.index）
• description 和 url 我们可以通过打开该 first.index 文件来观察

 

<?xml version="1.0" encoding="UTF-8"?> 

<!DOCTYPE QDOCINDEX> 

<INDEX url="http://www.firstqdocexample.com/0.1.0" title="First QDoc Exmaple" version="">

 ...

看到了没？它们是INDEX节点的两个属性。

文件作用

接下来呢，我们通过qt.index文件来解释xxx.index文件的作用。qt.index坐落于Qt安装目录下的doc/html中，你可以随时查看验证。

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE QDOCINDEX> 

<INDEX url="http://qt.nokia.com/doc/4.7" title="Qt Reference Documentation" version="4.7.0"> 

...

文件中的主要内容就Qt中所有类以及信号、槽、属性等的索引。

为了说明它的作用，我们修改Qt文档系统分析(一) 中所用的例子，添加一行indexes = $QTDIR/doc/html/qt.index (即我们使用qt.index):

project = First

description = First QDoc Exmaple 

url = http://www.firstqdocexample.com/0.1.0 

outputdir = html 

indexes = $QTDIR/doc/html/qt.index 

headerdirs = . 

sourcedirs = . 

outputencoding = UTF-8

执行

qdoc3 first.qdocconf

重新生成文档

 

看到区别了吗？

• 它显示出我们的Widget类继承自QWidget，点击QWidget可链接到qt在线文档中的QWidget的manual。
• 列出了它继承的所有public函数、信号、槽，这些也都可以链接到qt的在线文档

这些变化是怎么实现的呢？这就是我们的通过 qt.index 来实现的，因为这个文件中包含所有的索引信息，以及相应文档的http链接。

现在回头看看我们的 first.index,你能看到它的用处了吗？如果其他人需要继承我们的Widget类，那么，借助first.index文件，就可以自动链接到我们这儿生成的html文档(当然，我们要把它放到 url 所指定的地址处)。

配置html

查看Qt自带的文档，我们会发现，所有html页面的顶部和底部都是一样的，那么我们如何来实现这个效果呢？

在 xxx.qdocconf 文件中添加下列内容：

HTML.postheader  = "<table border=/"0/" cellpadding=/"0/" cellspacing=/"0/" width=/"100%/">/n" /

 "<tr>/n" /

 "<td class=/"postheader/" valign=/"center/">" /

 "<a href=/"index.html/">Home</a> &middot;" /

 " <a href=/"classes.html/">All Classes</a> &middot;" /

 " <a href=/"functions.html/">All Functions</a> &middot;" /

 "</td></tr></table>"  

HTML.footer             = "<p /><address><hr /><div align=/"center/">/n" /

 "<table width=/"100%/" cellspacing=/"0/" border=/"0/"><tr class=/"address/">/n" /

 "<td width=/"40%/" align=/"left/">Copyright &copy; 2010 dbzhang800</td>/n" /

 "<td width=/"20%/" align=/"center/">Trademarks</td>/n" /

 "<td width=/"40%/" align=/"right/"><div align=/"right/">First Program</div></td>/n" /

 "</tr></table></div></address>"

看下效果：

 

当然，还可以通过css对文档显示进行设置,格式如下：

HTML.stylesheets        = classic.css

另外，Qt文档的左上角一般都有一个logo的图片，那么这个图片怎么添加呢？

我们修改一下前面的postheader,并添加两天语句：

HTML.postheader         = "<table border=/"0/" cellpadding=/"0/" cellspacing=/"0/" width=/"100%/">/n" /

 "<tr>/n" /

 "<td align=/"left/" valign=/"top/" width=/"32/">" /

 "<img src=/"images/logo.png/" width=/"50/" height=/"40/" align=/"left/" border=/"0/" />/

 "</td>/n" /

 "<td class=/"postheader/" valign=/"center/">" /

 "<a href=/"index.html/">Home</a> &middot;" /

 " <a href=/"classes.html/">All Classes</a> &middot;" /

 " <a href=/"functions.html/">All Functions</a> &middot;" /

 "</td></tr></table>" 

extraimages.HTML        = logo.png 

imagedirs = .

• 首先准备一个一个 logo.png 图片，随便放入一个目录中，该目录通过 imagedirs 进行指定
• extraimags.HMTL 用来指示 qdoc3 将该图片拷贝到输出目录下的 images 目录中

• 在 HTML.postheader 中我们的使用方式就是  images/logo.png