Using Doxygen to generate Chinese documents for a C + + program

Article from: http://www.fmddlmyy.cn/text21.html

Annotate the source code in the agreed format, and use the tool to process the commented code to produce the document. Generating documents in this way has at least the following benefits:

• Easy to keep your code and documents in sync.
• You can manage your documents in versioning.

Many programming languages have similar documentation tools, for example: Java has Javadoc,ruby and RDoc. We can generate a document with Doxygen for C + + programs. This article describes how to use Doxygen on the Windows platform by creating a document for a C + + program, "who raises fish".

Doxygen is a better interface for making APIs, and CHM is a common format for such documents. The latest version of Doxygen (currently 1.5.2) uses UTF-8 as the encoding format for the output file, but Microsoft's CHM compilation tool does not support UTF-8, which can be problematic for making Chinese CHM documents. This paper presents a method to solve this problem.

1 Doxygen Introduction1.1 What to do

Using Doxygen to generate documents is primarily two things:

1. Write a configuration file (Doxyfile). After the general use of Doxywizard generated, and then manually modified.
2. Follow the conventions of Doxygen to "document" the code.

Then just execute the command:

doxygen Doxyfile

You can do it. Input files, output directories, parameters, and so on are all configured in Doxyfile.

1.2 What to get

Doxygen's output format is mainly HTML, LATEX, RTF, etc.:

• Doxygen when you export an HTML document, you can automatically prepare the project file (. hhp), catalog file (. hhc), and Index file (. hhk) used to make the CHM. Generates a CHM file after compiling with the CHM compiler (Hhc.exe) in HTML Help Workshop.
• Doxygen has prepared a makefile that is converted to PDF format while exporting Latex documents. PDF documents can be generated from latex documents as long as the appropriate Tex tools are installed on the system.
• The RTF format of the Doxygen output, which has been optimized for word, can be better converted to a Word document.

1.3 What you need

The following tools are required to complete the examples in this article:

1. doxygen the latest version, available from doxygen website download. The
2. graphviz is a graphical visualization software. Doxygen uses Graphviz to generate a variety of graphs, such as class inheritance diagrams, collaboration diagrams, header files containing diagrams, and so on. You can download the latest version of graphviz Web site style= font-size:14px "Graphviz". Doxygen uses the Graphviz layout engine dot, so it's called a dot in the document.
4. poplar authoring tool Fr.

can be from my home page http://www.fmddlmyy.cn download these tools: Doxygen 1.5.2 , Graphviz 2.12 , Iconv (GNU libiconv 1.9) and the FR 2.1.1.120 .

2 Chinese issues in CHM format

As mentioned earlier: At present, Doxygen Unified use UTF-8 as the output file encoding format, but Microsoft's CHM compiler tool (Hhc.exe) does not support UTF-8. If you compile directly with Hhc.exe, Chinese will not display correctly. The idea of solving this problem is simple:

• Convert the Doxygen output HTML file and the CHM project file (. hhp), catalog file (. hhc), and Index file (. hhk) to GBK encoding, and then compile with Hhc.exe.

The file can be encoded and converted using ICONV. For HTML files, in addition to the encoding conversion of the contents of the file,

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

Replace the "UTF-8" in the "gb2312".

2.1 Simplifying operations with batch processing

I've written some batch files (. bat) to simplify the process, including:

2.1.1 clean.bat--empty the previous output

@echo off
echo 清空以前输出
if exist refman.chm del /f /q refman.chm
if exist output\html del /f /q output\html\*.*
if exist output\latex del /f /q output\latex\*.*
if exist output\rtf del /f /q output\rtf\*.*
if exist output del /f /q output\*.*


2.1.2 build.bat--call Doxygen Generate document

@echo off
echo 生成文档
doxygen Doxyfile


2.1.3 utf82gbk.bat--Converts the specified file (wildcard character support) from Utf-8 encoding to GBK encoding

@echo off
echo 将%1从utf-8编码转换到gbk编码
for %%f in (%1) do copy %%f %%f.utf8
for %%f in (%1) do iconv -c -f utf-8 -t gbk %%f.utf8 > %%f


This batch file requires Iconv.exe on the system's current path. When executing iconv, use the-c parameter to ignore characters that cannot be converted. Otherwise, if the input file contains characters that cannot be converted, the conversion will fail. The input file is backed up to a file that has the. UTF8 suffix appended.

2.1.4 html-utf82gbk.bat--converts the specified HTML file (wildcard character support) from Utf-8 encoding to GBK encoding

@echo off
call utf82gbk %1
echo 将%1中的charset从UTF-8改为gb2312
fr %1 -f:charset=UTF-8 -t:charset=gb2312


This batch file requires the current path of the system to have Iconv.exe and Poplar the Fr.exe.

2.1.5 makechm.bat--using Doxygen output to make CHM files

@echo off
echo 将Doxygen输出文件编码从utf-8转换到gbk
set path=%path%;%cd%
cd output\html

echo 处理chm输入文件
call utf82gbk.bat index.hhp
call utf82gbk.bat index.hhc
call utf82gbk.bat index.hhk
call html-utf82gbk *.html

echo 生成chm文件
"C:\Program Files\HTML Help Workshop\hhc.exe" index.hhp

if exist index.chm copy index.chm ..\..\refman.chm
del /f /q *.chm
cd ..\..


This batch file assumes that the system has "HTML help Workshop" installed in the directory "C:\Program files\html help Workshop\". and assume that the output directory is the subdirectory output of the directory where Doxyfile is located.

2.1.6 rebuild.bat--to regenerate CHM files

@echo off
call clean.bat
call build.bat
call makechm.bat


2.2 Summary

friends who understand DOS commands should be able to read these batches with ease. After you place these batch files in your working directory (that is, the directory where Doxyfile is located), you can regenerate the CHM file each time you type rebuild. You can use the clean, build, and Makechm commands separately if necessary. UTF82GBK and HTML-UTF82GBK commands can also be used separately. Readers can download these batch files from my home page www.fmddlmyy.cn .

3 Creating a configuration file3.1 Preparatory work

"Who raises fish" is my recent writing a small program, it uses the reasoning method to solve the Einstein puzzle-"who raises fish". Readers can download the non-documented program from the exhaustive and reasoning: "Who raises fish" in C + + programs .

Before making a document, we need to complete the following preparations:

1. Install Doxygen, Graphviz, and "HTML help Workshop". I use the HTML Help Workshop version is 4.74.8702.0, English version. There is a Chinese version on the Internet, but the operation will be wrong.
2. Place the Iconv and FR programs in the directory that the system path contains, such as C:\Windows\System32.
3. Create an empty directory fish, put in the program you want to annotate (FISH\SRC), create a working directory (Fish\doc) of the authoring document, and place the batch file described earlier in the Doc directory.

OK, now you can run Doxywizard to create the configuration file.

You can simply click the "Save ..." button to save the configuration in Doc\doxyfile. At this point, the content of Doxyfile is the default setting for Doxygen. Doxyfile is an ordinary text file, we can open the editor directly. However, it is convenient to fill in the Doxywizard interface, each parameter has detailed hints. It is recommended to complete the first setup with Doxywizard. If you need to adjust individual parameters later, you can edit the Doxyfile directly.

3.2 Filling in the parameters

Click the "Expert ..." button to start filling in the configuration parameters.

:), does Doxygen have many parameters? In fact, most of the parameters have default values, need to fill in not too much, the following page description:

3.2.1 Project page

Doxyfile_encoding is the text encoding of Doxyfile. If you have Chinese characters in the file, you can fill in the GBK.

Fill in the project name (PROJECT_NAME), project version (project_number), Output directory (output_directory), and output language (output_language). The output directory can be filled in the relative directory of Doxyfile. The output language is equivalent to the program resource, select Chinese.

Doxywizard Chinese language support is not perfect, characters will be stored as garbled. We directly edit Doxyfile, fill in:

PROJECT_NAME = 谁养鱼

Cancels the full_path_names. We have modified the following parameters:

Doxyfile_encoding	GBK
Project_Name	Who keeps fish?
Project_number	1.0
Output_directory	Output
Output_language	Chinese
Full_path_names	NO

3.2.2 Messages Page

On the Messages page, fill in the Warn_logfile as Build.log. In this way, Doxygen will save the warnings and errors at compile time in the Build.log, and we can control the changes.

Warn_logfile

Build.log

3.2.3 Input Page

Specify the input source file directory (input) and change the entry file encoding (input_encoding) to GBK.

INPUT	.. \src
Input_encoding	GBK

The File_patterns parameter is the file type to be processed by Doxygen, and the default value includes all file types supported by Doxygen. You cannot document any file type with Doxygen. For example, Doxygen does not support assembler programs.

3.2.4 Source Browser Page

Select Source_browser to include the source code in the document.

Source_browser

YES

3.2.5 HTML page

When Generate_htmlhelp is selected, Doxygen prepares the project files, directory files, and index files that are required to generate the CHM files. You can customize the page with parameters Html_header and Html_footer, which is the file name that contains the custom content. For example, we can create a file html_foot with the following content:

<p align="right"><A HREF="http://www.fmddlmyy.cn/text20.html" target="_top">穷举和推理：用C++程序求解“谁养鱼”</A></p>
</BODY>
</HTML>

Then set the value of Html_footer to Html_foot.

Generate_htmlhelp	YES
Html_footer	Html_foot

3.2.6 Latex Page

Cancels the Generate_latex without producing LATEX output.

Generate_latex

NO

3.2.7 Dot Page

On the dot page, you can choose Uml_look, Call_graph, and Caller_graph. Call_graph is the function that calls other functions, for example:

Caller_graph is the caller of this function, for example:

Uml_look	YES
Call_graph	YES
Caller_graph	YES

3.3 Running Doxygen

For the "Who raises fish" example, the default value can be used for all other parameters. When you run Rebuild.bat from the command line into the doc directory (see Appendix 1), you can generate Refman.chm. At this point, we do not have any documentation of the program, the output contains only doxygen through dot generated.

We can edit doxyfile, set Extract_all to Yes, and then rebuild. At this point, Doxygen automatically extracts all the features of the program, including files, functions, variables, type definitions, enumerations, enumeration values, macro definitions, and so on.

just want to see the results of friends can download this CHM file . A detailed reference to all parameters in the Doxygen configuration file can be found in the "Configuration" page in the Doxygen manual. This concludes the previous article. The next article describes how to document a program.

PostScript (2007/7/15)

Many friends said that according to my instructions can not produce expected results, this must be my article is not clear, sorry. Recently, I have a lot of things in hand, I'm afraid I don't have time to write the next article in these months. Fortunately, the online introduction of Doxygen documentation of the article or a lot of, less I This article should also be nothing.

In fact, the purpose of this article is simply to get a friend who is unfamiliar with Doxygen a quick way to learn about the tool. If you really want to use Doxygen, you should spend more time looking at its documentation. I have packaged the working directory of the sample in this article on my home page www.fmddlmyy.cn and need friends to download . This is an unfinished version, I removed the Extract_all and commented on several functions. Because the annotations are incomplete, a non-empty build.log is also generated when compiling (in Doc directory rebuild). Log is a well-intentioned reminder to help us improve our documentation.

Appendix 1 Quick access to the command line and go to the specified directory

If you use the command line frequently, you can create a "command Prompt here" key and its subkey "command" under "Hkey_classes_root\folder\shell" in the registry, and set the default value of the "command" item to a string value " Cmd.exe ". At this point, simply right-click on any directory in the Explorer and select "Command Prompt here" to quickly go to the command line and go to the specified directory.

I will save this registry entry as reg File :

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here]

[HKEY_CLASSES_ROOT\Folder\shell\Command Prompt Here\command]
@="cmd.exe"




A friend you need can download and then double-click Import Registry.

On Vista, this does not go into the specified directory, nor is it necessary to do so. In Vista: Simply press the SHIFT key in the explorer and then right-click the folder and the menu item "Open Command Window Here" will appear. On the left side of the directory tree, this operation is not valid.

Using Doxygen to generate Chinese documents for a C + + program