| RMVL 2.4.0 Robotic Manipulation and Vision Library

载入中...
搜索中...
未找到
为 RMVL 撰写说明文档

上一篇教程：为基于 ARM 的 Linux 系统手动配置交叉编译

# Doxygen 概述

## 介绍

Doxygen 是用于构建文档系统的工具，包含非常多的实用特性，包括：

- 通过解析程序源代码来生成正确的文档
- 检查文档中的错误
- 插入图像和公式
- 使用 Markdown 标记语法，以及纯粹的 HTML 文本格式
- 以不同的格式生成文档，例如 HTML、LaTeX、man 等

## 安装

可在官方网站的下载和安装页面进行查看，一些 Linux 发行版也提供了有关 Doxygen 的包，例如 Ubuntu 可通过以下命令进行安装。

sudo apt install doxygen doxygen-gui graphviz

## 生成文档

- 获取 RMVL 源码
- 在项目文件夹顶层创建 build 文件夹，并 cd build
- 运行 cmake，或使用 cmake-gui
  cmake -D BUILD_DOCS=ON ..
- 运行 make
  make doxygen
- 在你的浏览器中打开 'doc/doxygen/html/index.html' 文件

# 快速开始

以下内容为 RMVL 特有的文档，若是自己书写的其他项目，文档的布局、协议都可以视需求情况而定。

## 文档布局

有关文档的一切内容均放置在 <path-to-rmvl>/doc 中，下面列举一些关于文档生成重要的部分

- Doxyfile.in - 由 cmake 自动生成 Doxyfile，来为 make doxygen 提供文档构建指南。内部定义了有关文档构建范式的所有内容，包括构建类型（HTML、LaTeX 等）、构建工作空间、源代码中的构建内容等；
- doxygen-awesome.css - 样式文件，源自于 GitHub 的 doxygen-awesome-css 项目；
- header.html, footer.html - 定义了页眉与页脚的格式，其中包含一些 js 脚本的导入；
- root.markdown.in - 由 cmake 自动生成 root.markdown，作为文档首页

此外，RMVL 的文档在构建中会自动递归索引项目顶级目录下的所有文件，最终生成包含以下几个部分

- 源代码 中的实体，包括类、函数、枚举等内容，这些内容需要被定义在相应的头文件中。

  注解
    自动的代码解析会寻找所有的头文件（".h, .hpp"）以及部分源文件（"sample_*.cpp"）的内容
- 页面 是放置与任何源代码实体不直接连接的图像和代码示例的大块文本的区域，页面应该位于单独的文件中，并包含在几个预定义的位置，比如说本教程就是这样一个页面的例子。
- 图像 可以用来说明所描述的事物，这些文件通常位于与页面相同的位置，可以插入到文档的任何位置。
- 示例代码 展示了如何在实际应用程序中使用该库，每个示例都是代表一个简单应用程序的自包含文件。这些文件的部分内容可以包含在文档和教程中，以演示函数调用和对象协作。
- 参考文献 用于创建一个公共的书目，所有作为 RMVL 功能基础的科学书籍、文章和论文集都应列入此 参考文献 。

## 详细内容

为了给类、函数或其他实体生成文档，需要使用特定的注释方式，比如说

    /**
     * @brief 计算相机中心与目标中心之间的相对角度
     * @note 公式推导参考函数 @ref calculateRelativeCenter() ，现直接给出结果 \f[\begin{bmatrix}
     *       \tan{yaw}\\\tan{pitch}\\1\end{bmatrix}=\begin{bmatrix}f_x&0&u_0\\0&f_y&v_0\\0&0&1
     *       \end{bmatrix}^{-1}\begin{bmatrix}u\\v\\1\end{bmatrix}\f]
     *
     * @param[in] cameraMatrix 相机内参矩阵
     * @param[in] center 像素坐标系下的目标中心
     * @return 相对角度，目标在图像右方，point.x 为正，目标在图像下方，point.y 为正
     */
    cv::Point2f calculateRelativeAngle(const cv::Matx33f &cameraMatrix, cv::Point2f center);

### 1 基本命令

#### 1.1 brief

表示一段函数、类、枚举、结构的简要信息

#### 1.2 param

通常表示函数的参数，包含传入、传出、传入兼传出参数 3 种，可分别用 [in]、[out] 和 [in out] 做区分，例如

    @param[in] cameraMatrix 相机内参矩阵

结果如下

参数

  [in] | cameraMatrix | 相机内参矩阵

#### 1.3 note

注解，可包含对类、函数的详细介绍或者使用注意事项，也可包含一些公式信息，具体的公式写法在后续的 f 会进行介绍，note 的使用如下

    @note 公式推导参考函数 @ref rm::calculateRelativeCenter

结果如下

注解
  公式推导参考函数 rm::calculateRelativeCenter

#### 1.4 warning

警告，可包含对类、函数的潜在问题或使用注意事项

    @warning 不建议手动创建对象

结果如下

警告
  不建议手动创建对象

#### 1.5 return

表示返回值

    @return 相对角度

结果如下

返回
  相对角度

#### 1.6 f 公式

内联公式使用 f$ 命令开始

    \f$ ... \f$

块公式使用 f[ 和 f] 命令

    \f[ ... \f]

示例

    若状态向量包含以下内容：\f$[p, v, a]\f$ ，然而观测向量仅包含 \f$[p, v]\f$，
    在这种情况下，需要使用一个观测转换矩阵 \f$H_{2\times3}\f$。在上述例子中可表示为
    \f[\begin{bmatrix}p\\v\end{bmatrix}=\begin{bmatrix}1&0&0\\0&1&0\end{bmatrix}
    \begin{bmatrix}p\\v\\a\end{bmatrix}\f]

结果如下

若状态向量包含以下内容： \([p, v, a]\) ，然而观测向量仅包含 \([p, v]\)， 在这种情况下，需要使用一个观测转换矩阵 \(H_{2\times3}\)。在上述例子中可表示为

\[\begin{bmatrix}p\\v\end{bmatrix}=\begin{bmatrix}1&0&0\\0&1&0\end{bmatrix} \begin{bmatrix}p\\v\\a\end{bmatrix}\]

#### 1.7 defgroup 与 addtogroup

用于创建模块组，方便对类、函数进行分类管理，具体的使用方法可参考 RMVL 源码中的 include/rmvl/ 目录下的各个模块

### 2 页面相关

#### 2.1 Markdown 支持

Doxygen 支持部分 Markdown 语法与扩展，本篇教程页面同样使用了很多的 Markdown 语法。

#### 2.2 标题 ID

每个文档页面都应该为自己设置一个 ID，比如本篇教程的标题和 ID 如下

    为 RMVL 撰写说明文档 {#tutorial_document}

#### 2.3 子页面与跳转

使用以下命令进行子页面的跳转

    @subpage xxx

使用以下命令进行页面内或其他地方的引用

    @ref xxx

### 3 代码块

使用以下命令创建代码块

    @code{.cpp}
    std::cout << "Hello World" << std::endl;
    @endcode

渲染结果如下

std::cout << "Hello World" << std::endl;

### 4 按钮

使用以下命令创建按钮

    <div class="tabbed">

    - <b class="tab-title">C++</b>

      This is C++.
      ```cpp
      std::cout << "Hello World" << std::endl;
      ```

    - <b class="tab-title">Python</b>

      This is Python.
      ```python
      print("Hello World")
      ```

    </div>

渲染结果如下

- C++

  This is C++.

  std::cout << "Hello World" << std::endl;

- Python

  This is Python.

  print("Hello World")

# 参考

- Doxygen - Doxygen 主页面
- Documenting basics - 如何在代码中包含文档内容
- Markdown support - 支持的标记与扩展
- Formulas support - 如何包含公式