文档自动生成 Doxygen+Sphinx

Doxygen介绍

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxygen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。

为什么要用Doxygen

作为一名合格的程序员，我认为会写文档是很重要的，但是又不想花很多时间整理文档，那么doxygen是一个很好的工具。

其实我们看到很多网站文档api，都是由doxygen自动生成的,使用doxygen可以提高我们工作效率。

lwIP: OS mode (TCPIP thread)

mbed TLS v2.16.1 source code documentation - API Documentation - mbed TLS (Previously PolarSSL)​​​​​​

安装过程

1.系统安装

sudo apt-get install doxygen doxygen-gui

2.在命令行输入"doxywizard",会弹出配置UI

 

 此外，你可以通过命令行来自动执行doxygen配置

doxygen DOXYFILE

 

 

Sphinx 与 Breathe

Sphinx 目前的『市场』占有率非常高，因为它有免费的文档托管 Read the Docs，支持线上预览以及版本历史等，由此大多数的 Python 文档都是选择它来生成文档的。

对的，你没听错，一开始它确实是为了 Python 文档而出现的，后来也逐渐支持其它语言，包括 C/C++，只是，Doxygen 与 Sphinx 不能直接关联，即 Sphinx 不能直接使用 Doxygen 生成的内容来生成 Sphinx 文档，它还需要一个插件来做适配，Breathe 就是为了连接 Doxygen 与 Sphinx 而生。

Sphinx 默认的解析文档是 reStructureText，你可以认为是高级版本的 Markdown，也就是比它功能更强大。当然，你也可以使用 Markdown 来写文档，它有一个专门的插件来做这件事。

先准备index.rst 文件

My Awesome project's documentation!
===================================
This project for DX

main.c
^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfile:: main.c

Indices and tables
==================

* :ref:`search`

 输入命令行

sphinx-quickstart

按照提示操作，自动生成conf.py文件

修改conf.py文件，修改以下几行代码

import os 
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]



breathe_projects = { "t31_doxygen": "./output/xml" }
breathe_default_project = "t31_doxygen"
##添加以上代码

输入以下命令行，自动生成网页

make html

最终实现的效果图如下