自定义Doxygen生成小而美的文档


Doxygen是因代码文档而生,他的特点在于:

  • 文档与代码融为一体,注释就是文档
    • 代码有变更,注释跟着改,文档也跟着出来
    • 文档也可以使用Git版本管理
  • 可根据源代码&注释生成漂亮的文档出来,比如常见的html

Doxygen在近期的版本支持了markdown语法,极大简化了一些富文本元素的语法,如标题,列表,表格,图片,链接等等,而且markdown在软件界很流行,经常逛Github, stackoverflow,经常写博客的人运用markdown更加得心应手。

Java有JavaDoc, Python用Sphinx,Ruby用RDoc, 我们C/C++开发者当然用Doxygen.

当然,个人认为Doxygen也有不够好的地方,比如:

  • 生成的文档比较凌乱,冗余项很多,不够清晰,简单
  • 默认的样式比较丑
  • 自定义比较复杂
  • 对小型项目/组件/可复用代码不太友好

接下来,后阐述下Doxygen的常见功能和描述我的自定义之路 - 为小型代码打造一个清晰简单的文档。

Getting Start

doxygen文档如何生成,是根据一个配置文件指定的,在这个配置文件指定输入源代码,输出路径,使用的样式表等等。

第一步:生成默认配置文件

$ doxygen -g Doxyfile

第二步:修改配置文件

最主要的是修改输入,输出,其他的属性我们在下文再讲。

INPUT                  = ../app                      \
                         ../components               \
                         ../doc                      \
                         ../README.md
RECURSIVE                         
OUTPUT_DIRECTORY       = ../output/doxygen 

第三步,生成文档

$ doxygen ./Doxyfile

Documenting the code

Doxygen 官网上写的很详细了,移步这里:

  • http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
  • 语法/命令:http://www.stack.nl/~dimitri/doxygen/manual/commands.html

这里,仅仅强调一下group, 善用group可以让文档更有组织,更有条理。

设置group的层次关系

//*****************************************************************************
//
//! \addtogroup HD44780
//! @{
//!     \addtogroup HD44780_HelloWorld Hello World
//!     @{
//!         \addtogroup HD44780_HelloWorld_PutString Put String
//!         @{
//
//!         @}
//!     @}
//! @}
//
//*****************************************************************************

在.md文件中定义group

当需要大篇幅图文文档描述这节的话,可以把这个group拉倒一个 markdown文件中去

Doxygen对markdown也扩展了一些语法,但大体差不多,详细移步: http://www.stack.nl/~dimitri/doxygen/manual/markdown.html

@defgroup HD44780_HelloWorld_PutString Put String
@brief An Simple example to show put a sting using the lcd.

TODO: 以下是这个Group的详细文档描述,如果需要的话

配置文件

官网:http://www.stack.nl/~dimitri/doxygen/manual/config.html 列出了所有的配置,这里,我挑选了一些经常要改了。

当需要自定义特别的扩展名时

EXTENSION_MAPPING      = example=C++    

是否安装字母排序Group

SORT_GROUP_NAMES       = YES    

当需要使用类似C语言的根据#ifdef条件生成不同的文档时,使用

ENABLED_SECTIONS       = DOXYGEN_PROJECT

上面的代码用来定义一些条件,这样使用:

@if (DOXYGEN_PROJECT)
@defgroup HD44780
@endif

通过一个layout.xml文件自定义布局,比如是否显示Class

LAYOUT_FILE            = ./config/layout.xml

如果需要把一个源代码直接插入到一个markdown文档中,那么需要指定Example的根目录

EXAMPLE_PATH           = ../    

文档中这样插入源代码

@include hd44780_config.h

如果需要把一个.md直接作为首页的话,需指定:

USE_MDFILE_AS_MAINPAGE = ../README.md    

自定义Html的头,尾,CSS,

HTML_HEADER            = ./assets/include/header.html
HTML_FOOTER            = ./assets/include/footer.html
HTML_EXTRA_STYLESHEET  = ./assets/stylesheets/style.css

当不需要生成菜单导航条

DISABLE_INDEX          = YES

是否需要生成一个树形的导航

GENERATE_TREEVIEW      = YES

告诉doxygen你想声明哪些宏,然后doxygen会根据编译预处理,生成不同的文档 </pre> PREDEFINED = </pre>

自定义输出

首先生成模版,然后自己更改模版

doxygen -w html header.html footer.html style.css

更改CSS

我不太想要Doxygen默认出来的导航,和树形导航,我比较喜欢单页的效果,在加上一个类似 Table of Content的导航

2014-10-15-doxygen-screen.png

生成后动作

因为多多少少,文档中会有一些图片,附件等等,然后直接是网上的链接也可以,但是我们也可以一起跟代码放在一起,那么文档可能就需要执行一些copy的动作。

这里,我把整个动作写到一个makefile中,通过make来完成这一系列操作。

我的配置

可以移步到我的github项目看:

https://github.com/ahnniu/component-doc-proposal