6. 生成API文档

可以配合使用sphinx+reST+breathe+doxygen来给代码生成API文档并无缝添加到已有的文档结构中。

6.1. Step1

运行:

doxygen -g

生成doxygen配置文件(默认文件名是Doxyfile)，然后修改此文件：

  • 项目名称 PROJECT_NAME = “MyProject”
  • 对C项目优化 OPTIMIZE_OUTPUT_FOR_C = YES
  • 源文件路径 INPUT = /home/tom/project/include
  • 源文件编码 INPUT_ENCODEING = UTF-8
  • 生成XML GENERATE_XML = YES 因为要使用breathe扩展，所以必须生成xml
  • XML输出目录 XML_OUTPUT = my_xml
  • 不需要生成html GENERATE_HTML = NO
  • 不需要生成latex GENERATE_LATEX = NO
  • 不显示包含文件 SHOW_INCLUDE_FILES = NO

6.2. Step2

运行:

doxygen [Doxyfile]

输出注释，主要是xml。

6.3. Step3

配置conf.py，以支持breathe扩展。前提是这一扩展已经安装。

加入扩展:

extensions = ['breathe']

配置breathe:

breathe_projects = { "myproject": "./my_xml" }
breathe_default_project = "myproject"
breathe_domain_by_extension = {"h" : "c"}

6.4. Step4

按breathe扩展语法编写rst文件，比如:

My API
==========

sp.h
----

.. doxygenfile:: sp.h

上面的语句为项目中的sp.h接口文件生成了html文档。

最后，运行 make html 生成html即可。

在这些步骤中，需要先调用doxygen生成xml，再调用sphinx-build(make html时自动调用)生成最终文档，如果想一步完成，可以在Makefile中加入doxygen调用:

html:
->>>doxygen Doxyfile
->>>$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
->>>@echo
->>>@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."