Debian下使用Doxygen生成定制样式的开发文档

背景：
别人会用到我们平台的功能接口，但当前平台没有功能使用文档，很多接口别人不知道具体用法。而我们又不想单独维护一个平台使用文档，每次更新类或接口还要再单独刷新下使用文档是件很痛苦的事情。故我们使用了Doxygen工具自动生成产品文档，每次修改代码只要添加或者更新注释即可直接更新产品文档，很是方便。

目标：
凡事要有目标，然后才好有的放矢吧。
我们要提供网页版的开发文档，页头有公司logo, 文档名称，文档版本号，以及最右侧的搜索框。
页面最左侧是个导航树，导航树分三大层级：
第一层介绍此开发文档怎么使用，以及我们的平台如何安装和使用。

第二层根据平台每个模块的功能，分别写对应功能的介绍，以及如何使用。
数据源： 本层的数据源是手工编写的Markdown文件，也就是后缀是 .mk的文件。在每个模块目录下创建 README.mk 文件，然后再在子模块目录下创建 moduleName.mk文件

第三层是各个模块实现的类所有接口。如果根据第二层的介绍还满足不了你的开发需求，可以再看第三层看更多的接口功能使用。
数据源： 本层的数据源是代码的.h文件中的注释及代码本身，Doxygen工具会自动提取你的代码注释以及解析代码结构获取到类的所有接口信息。

页面右侧就是具体内容显示区域，无需赘述。

环境： Debian, 内核版本 4.9.0-12

1、如何使用Doxygen工具？

首先安装Doxygen工具
$ sudo apt-get update
$ sudo apt-get install doxygen

2）生成Doxygen的主配置文件
$ doxygen -g [configure file name]
直接使用上面命令生成配置文件样例，最后的参数是配置文件的名称。如果不写配置文件名称，会生成名称为Doxyfile的配置文件。

3）如何配置Doxyfile配置文件
打开配置文件，会发现有很多参数，而且每个参数前会有注释，可以根据注释尝试着修改，或者网上搜索看用法，又或者可以自己修改测试看下效果。下面罗列一些我根据自己需要修改的主要参数：
PROJECT_NAME：产品名称
PROJECT_NUMBER：产品版本号
PROJECT_LOGO：Logo图片，建议长*宽不大于 55 * 200 像素
OUTPUT_LANGUAGE：输出语音，可以用中文 Chinese
LAYOUT_FILE = ./config/layout.xml 在layout.xml定制界面的布局，导航树结构就是由此文件定制。可以通过如下命令生成模板文件：
$ doxygen -l （后面是字母L的小写）

DISABLE_INDEX = YES 禁用菜单索引，这个索引很鸡肋，不好用
GENERATE_TREEVIEW = YES 开启左侧导航树

HTML_HEADER = ./assets/include/header.html
HTML_FOOTER = ./assets/include/footer.html
HTML_EXTRA_STYLESHEET = ./assets/stylesheets/style.css
这三个参数用来定制页头，页脚以及样式。可以通过下面命令生成模块，然后修改定制。
$doxygen -w html new_header.html new_footer.html new_stylesheet.css

4）如何配置布局文件，即步骤3）中的LAYOUT_FILE
在配置文件中有两大部分内容，第一部分是导航的结构的设置，第二部分具体显示内容的设置。如果你需要显示什么，就在对应的属性visible设置成yes, 否则设置成 no.下面重点说下导航设置，具体的内容显示使用默认值即可。

doxygen自带的菜单导航显示如下图：

mainpage: 主页面设置，打开后就首先显示的页面，对应上图的Main Page
pages: 对应上图的Related Pages
namespaces: 代码里的所有命名空间，对应上图的 Namespaces菜单
classes: 代码里的所有的类，对应上图的 Classes菜单
files: 代码源文件，对应上图的Files菜单
examples: 代码里测试用例，对应上图的 Examples菜单
还有一个modules项，不太清楚干啥用的，我没用到。

对于上面的导航项如果你需要就定制它，让它的visible为yes, 否则直接不显示即可。那么
如果在导航树添加自己定义的目录层次？
1、通过type=“usergroup"添加根目录，例如
< type=“usergroup” visible=“yes” title=“add root directory” url=”@ref RootDirectoryPage">

2、通过type=“user"添加子目录，例如
< type=“user” visible=“yes” title=“add sub directory” url=”@ref SubDirectoryPage">

是不是发现上面还有个url链接参数，它的作用可大了，可以帮助我们建立到某个页面的跳转链接，上面的RootDirectoryPage和SubDirectoryPage是我们定义的页面名称。
还记得上面目标->第二层的数据源吗？我们编写的每个markdown文件都会被doxygen生成一个网页，我们在md文件的第一行标题后添加 {#RootDirectoryPage}就可以给这个网页起个名字，后面使用 url="@ref RootDirectoryPage" 就可以链接到此网页。md文件首行格式参考： # 根目录 {#RootDirectoryPage}

//todo 待继续刷新

Debian下使用Doxygen生成定制样式的开发文档相关推荐

DotNet 项目开发文档的自动生成和相关工具的使用
在 VS.Net 的 IDE 中对C#提供了一些可以自动生成的 XML 注释,使用这些注释可以对代码中定义的对象进行说明.注解:通过设置项目属性,在生成项目时,可以让VS.Net自动的将这些注释信息输 ...
.NET6使用DOCFX根据注释自动生成开发文档
本文内容来自我写的开源电子书<WoW C#>,现在正在编写中,可以去WOW-Csharp/学习路径总结.md at master · sogeisetsu/WOW-Csharp (gith ...
rap技术原理_RAP如何自动在方法上生成前端开发文档
针对阿里妈妈前端大牛来说这个工具的诞生,为java开发人员节约了多少开发时间.非常感谢. 废话不多说直接看源码: 安装说明大家可以根据上面的文档源码来直接部署.重点来了.重要的话说三遍.idea如何完 ...
Unity游戏开发文档（3.1.2）：下拉式音乐选择菜单
前言该文档为<Unity游戏开发文档(3):Dancing Line>的附属文档,亦可看作是单独的技术总结文档. 目录综述构建下拉菜单填充下拉菜单切换背景音乐最终效果 ...
开发文档生成工具--Doxygen
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C.C++.Java.Objective-C和IDL语言,部分支持PHP.C#.注释的语法与Qt-Doc.KDoc和J ...
[技巧]使用Xcode集成的HeaderDoc自动生成注释和开发文档
Doxygen本来是一个很好的工具,可是我感觉在mac系统下,如果用doxygen最后生成的CHM文件感觉就不是那么恰当,应为本身CHM是微软的产品,苹果系统上并不是很通用,很经常出现文件乱码的情况. ...
使用 ApiGen 生成开发文档
转载地址:http://www.th7.cn/Program/php/201501/375666.shtml ApiGen官网: http://www.apigen.org/ 一.从 github 获 ...
python-docx中文开发文档_使用Python语言-docx生成Word文档
本文主要向大家介绍了使用Python语言-docx生成Word文档,通过具体的内容向大家展示,希望对大家学习Python语言有所帮助. < 学会来使用python操作数据表和PDF,今天我们尝试 ...
可以一键生成crud的php框架,一键生成CRUD - FastAdmin框架文档 - FastAdmin开发文档
一键生成CRUD 最后更新时间:2021-01-05 19:54:10 在FastAdmin中可以快速的一键生成CRUD,其中包括控制器.模型.视图.验证器.语言包.JS. 准备工作在数据库中创建一 ...
linux pcf8563开发文档,linux下的i2c与时钟芯片pcf8563通信
2012/7/19 linux下的i2c与时钟芯片pcf8563通信 by: 韩大卫 @吉林师范大学 1,本程序增加了对星期寄存器(wday)的写操作. 2, 本程序将i2c-test 改为rtdat ...

Debian下使用Doxygen生成定制样式的开发文档

Debian下使用Doxygen生成定制样式的开发文档相关推荐

最新文章

热门文章