Doxygen介绍
Doxygen是一种开源跨平台的,以类似JavaDoc风格描述的文档系统,完全支持C、C++、Java、Objective-C和IDL语言,部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxygen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX、RTF参考手册。
为什么要用Doxygen
作为一名合格的程序员,我认为会写文档是很重要的,但是又不想花很多时间整理文档,那么doxygen是一个很好的工具。
其实我们看到很多网站文档api,都是由doxygen自动生成的,使用doxygen可以提高我们工作效率。
安装过程
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
最终实现的效果图如下