OpenCASCADE Documentation System

Abstract. Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages. You can also use doxygen for creating normal documentation, as OpenCASCADE did for its references and user’s guide documents. 

Key Words. OpenCASCADE, Doxygen, Documentation System 

1. Introduction

Doxygen基本上已经成了从C++代码生成文档的一个标准工具。OpenCASCADE就利用Doxygen来根据源代码生成References文档，还利用其生成HTML和PDF格式的User Guide文档。使用Doxygen来生成文档，只需要按照一定的格式，就可以自动生成看上去比较专业的文档。 

本文主要对Doxygen用来生成User Guide的方法做一定的介绍。根据代码生成References文档的方法请参考Doxygen的文档说明。 

Figure 1.1 Doxygen GUI 

2. Prerequisites

为了自动生成PDF格式的文档，还需要准备全如下工具： 

v Doxygen 1.8.4版本及以上； 

v Graphviz的Dot，用来生成文档中的类图； 

v MikTeX：用来生成PDF格式的文档； 

v Inkscape：只有当要生成PDF格式中带有SVG格式的图片时需要； 

v MathJax：当生成的HTML或CHM中有数学公式时需要； 

这些工具都可以从网上下载得到。 

3. Markdown Support of Doxygen

Markdown支持是从Doxygen1.8.0开始的，Markdown就是还格式语法的普通文本，由John Gruber编写，其目的是： 

The design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. 

当你按照Markdown格式来写文档时，只需要将*.md文件放到文档文件夹中，Doxygen会自动搜索并生成相对应的文档。这里列举几个Markdown的例子。 

3.1 Tables表格

生成表格可以用如下的文本来表示： 

生成的表格样式如下图所示： 

Figure 3.1 Tables in Markdown 

3.2 Code Blocks代码片段

使用~~来隔离代码，若在其带上后缀名，还将根据后缀名来给代码高亮。如下所示为给C++代码着色： 

Figure 3.2 Code blocks in Markdown 

小段代码着色也可用标记@code和@endcode来标记。 

3.3 Images插入图片

插入图片使用如下标记： 

Figure 3.3 OCC logo 

4. Conclusion

使用OCC这种方式来生成文档，感觉还是很不错的。我就使用这种方式生成了程序IsoAlgo的文档，看上比较专业，如下图所示： 

Figure 4.1 IsoAlgo User Guide