doxygen教程-9-使用Markdown

Markdown 简介

Markdown 是一种广泛使用的, 用于编写文档的语法. 相比于常用的 Word, 利用 Markdown 可以非常方便地控制格式, 从而专注于写作. 当然, 论功能, Word 是完胜的, 但是在程序开发的语境下, Markdown 是更舒适的选择(即使表格和图片是硬伤 T.T );

在 github, gitee 等代码托管网站, 仓库目录下的 README.md 会被自动渲染并显示出来. CSDN, 知乎等文章发布平台也都支持用 Markdown 写文章. doxygen 则在 1.8.0 版本引入了 Markdown 的支持.

不太了解 Markdown 的同学可以自行网上搜索教程, doxygen_manual-1.9.2.pdf -> Chapter 5 -> Markdown support 也完整地介绍了 Markdown 的语法. 比较好用的 Markdown 编辑器是 Typora.

在注释中使用 Markdown

我们可以在注释中使用 Markdown, 例如

/** @brief 一个名为 fun 的函数;
 *  @detais
 *  ## 这是一个标题:
 *  这个函数可以干这些事:
 *      - 事情 1
 *      - 事情 2
 * 看看这个[超链接](cn.bing.com)
 */
void fun();

上面的注释, 输出成文档后是这样的

可以看到, 文档中出现了标题, 列表, 超链接等结构.

利用 Markdown 编写网页

有时我们文档的内容不完全来自于代码的注释, 例如安装说明, 使用说明, 或者教程这类内容, 我们希望放到单独的文件里, 而不是放到源文件里和代码混在一起. 有些人可能习惯用 Word 来编写这类文档, 不过在 doxygen 的配合下, Markdown 是个更好的选择.

Markdown 文件的扩展名是 .md 或 .markdown. doxygen 会将每一个 Markdown 文件视为一个页面(page), 在 html 输出中, 也就是一个网页.

下面我们新建一个目录 hello_doxygen3, 然后在该目录下新建一个纯文本文件 page1.md, 然后用 Typora 打开(用记事本, Notepad ++ 等工具也可以), 输入以下内容:

# 软件使用手册

## 软件简介
本软件具有如下功能点:
    - 功能 1;
    - 功能 2;
    - 功能 3;

## 下载
    - [官网下载链接](xxxx/.com/download)
    - 找[度娘](www.baidu.com)下载

## 安装
安装过程非常简单,按如下步骤操作即可:
    1. 点击 "下一步";
    2. 点击 "下一步";
    3. 点击 "下一步";

然后, doxygen -g 生成配置文件, doxygen Doxfile 输出文档, 可以看到, 导航栏多了 “Related Pages” 一项

点进去, 页面是这样的

标题及首页

标题(title), 就是 “Related Pages” 的链接列表中, 链接的名字, 也是链接点进去之后, 那个页面的标题.

如果 Markdown 文件以一个 header 开头, 也就是本例中的 ## 软件使用手册, 则标题就是这个 header, 否则(以其他类型的文本开头), 就以文件名作为标题.

此外, 如果第一行的 header 的 label id 是 mainpage 或 index, 也就是写成下面这样:

## 软件使用手册 {#mainpage}

或

## 软件使用手册 {#index}

则这个文件将在首页(index.html)显示.

label id 是 Markdown 的扩展语法.

用 special commands 编写网页

实际上 doxygen 在输出文档时, 对 Markdown 文本的处理方式是, 首先利用 Markdown 预处理器转化成包含 special commands 和 HTML 标签的文本, 然后再将这个中间结果转化成各种格式的文档. 所以, 利用 doxygen 自身的命令也可以写出上述的页面. 以下是涉及到的部分指令:

@mainpage
@page
@section
@subsection
@ref

下面这段注释生成的页面和上述用 Markdown 生成的页面效果是一样的, 并在首页显示. 通常将这类 C 注释专门放到 .dox 文件中. 如果不需要作为首页, 则将 @mainpage 替换成 @page.

/**
@mainpage 

@section 软件简介
本软件具有如下功能点:
    - 功能 1;
    - 功能 2;
    - 功能 3;

@section 下载
    - <a href="xxxx/.com/download">官网下载链接</a>
    - 找<a href="www.baidu.com">度娘</a>下载

@section 安装
安装过程非常简单,按如下步骤操作即可:
    1. 点击 "下一步";
    2. 点击 "下一步";
    3. 点击 "下一步";
*/

鉴于二者功能一致, 但 Markdown 的使用更加广泛, 所以学习 Markdown 的收益更高些. 因此仅作一例, 以增进了解, 不再深入介绍相关命令(其实是我不想再深入研究了).