Doxygen + Graphviz + Htmlhelp, become a good document

1 Doxygen is a well-known code documentation tool.

Download Address: www.doxygen.org

Install it. Http://www.stack.nl/~dimitri/doxygen/download.html can be downloaded.

2 Graphviz

This tool is used with Doxygen, can extract functions, the call between modules is close, very clear.

Download Address: http://www.graphviz.org/Download..php

Here are some diagrams extracted by Graphviz:

3 HTMLHelp

This tool transforms the HTML file generated by Doxygen into a CHM file, which looks more convenient. Download Address:

http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

Install it.

When all is installed, you can start using it.

Run Doxygen Wizard.exe

Run Doxywizard.exe, then follow the instructions in Doxywizard Usage section of the document (Doxygen_manual-1.5.2.chm) in the Doxygen root directory. Mainly includes, source path, work path, output path and so on.

Point, you can generate a document

Finally, some problems encountered during the process of document generation are explained:

1 Chinese question: The Chinese annotation is garbled in the document.
Workaround: Fill in the "GB2312" in the input_encodeing of the input Options page in expert so that the code generated by the GB-based text editor will work.

2 Graphics Problem: cannot draw graph of Class diagram collaboration diagram.
First make sure to install Graphviz, note that is not Wingraphviz, the latter is a Graphviz COM encapsulation, but Doxygen is not based on it developed, so it is useless to install. Then fill in the Graphviz installation path in the expert dot page dot_path. Then select the graphics category you want to generate in the wizard diagram.

If you receive an error that cannot contain the. map file, you can set the working directory to HTML and clear all files in the HTML to try again. The cause of the problem is still uncertain.

3 Output CHM problem: How to output. chm file
1. You must install Microsoft or its compatible CHM compilation system. Typically HTML Help Workshop.

2. First in the [Wizard] Output page, select HTML and then select to prepare for compressed HTML (. chm).

3. Next in [Expert] HTML page, will hhc_location point to Microsoft's HHC tool. Usually C:/Program files/html help Workshop/hhc.exe. Then click OK, save, compile.

Enter the path to the Hhc.exe file in Hhc_location. Hhc.exe can be obtained by installing HTML Help Workshop.

4 How to display the list of functions in the left tree, like MSDN.
Open the HTML page for [Expert], and then select Toc_expand.

5 How to remove the Chi file attached to the CHM.
Note that by default, the CHM will have a Chi file that appears to be used to speed up indexing. I have also encountered many users have only uploaded a chm, but did not upload the Chi file, resulting in the situation can not be properly displayed. I don't know if I can recreate the Chi file with a tool, but I think it's OK to turn it off. Open the [Expert] HTML page and cancel the Generate_chi.

6 How to display a function on the right side of the page like MSDN.

The problem is actually tricky, and in [Expert] the project page, here's an option called Separate_member_pages, which selects the option so that each function is a page. But there's a problem, which is that there's a list of all the functions on the right side of the page. Unfortunately, after research, this really can't be removed. My solution is to compile the Doxygen myself, Container->writequickmemberlinks (OL,MD) in the Writedocumentationpage function of memberlist.cpp; Along with a few lines to shield off.

7 How to remove the group information from the CHM when the Subgrouping is selected.

This feature lists the list of functions directly in the left tree of the CHM without having to click on the right page. This feature needs to modify the source code. In Index.cpp, the doxygen::indexlist.addcontentsitem,doxygen::indexlist.inccontentsdepth of the shielding Writegroupindexitem function and Doxygen::indexlist.deccontentsdepth ();

8 How to modify or remove the right generated at ... of the text.

Open [Expert ...] HTML page, and then specify the corresponding HTML file in Html_footer. Note that the html_footer contains at least body and HTML end tags. That is, a minimal tail HTML is at least so </BODY></HTML>. Similarly, if you want to specify the Html_header, he contains at least <HTML><HEAD></HEAD><BODY>

9 How to generate a group.

A group is a way to display the same kind of function under a root. Doxygen supports grouping, that is, you can put the relevant code through the logo, into the same group, easy to view. This is mainly through several built-in syntax commands. First, you define a group by @defgroup, and then you add groups of functions or classes to the group by marking @ingroup. In this way, the corresponding functions are placed in the same group.

10 How to generate Chinese help.

Click [Expert], in Page project's output_language, select Chinese, so the output of the help message is Chinese. The text of the specific Chinese hint message is in the source code.

11 How to solve the garbled problem of Doxygen output Chinese CHM completely.
There are probably three coding settings in the Doxygen implementation. First, Doxyfile, which is the configuration file. Second, input_encoding, which is the encoding of the input file that Doxygen needs to parse. Finally, the output is encoded. For example, the index code on the left side of CHM.

The first is the CHM title garbled, this is better to solve, because Doxywizard use QT to do the interface, it has done the conversion, so in the Doxywizard input Chinese, in the preservation of time, he made a transcoding, resulting in the doxyfile of the final save information is incorrect. This time only need to use Notepad to open the Doxyfile configuration file, enter the corresponding Chinese can. Note that when you save it, you can save it as an ANSI encoding. Save in other formats, you may need to remove the BOM, more trouble, no research. This corresponding encoding is set in [Expert ...] , the doxyfile_encoding of page Project is not entered or the default is UTF-8.

Next is the right content garbled, this is mostly because you did not configure the input file encoding type caused. In [Expert ...] Input page, there is a input_encoding, this option represents the encoding of the input file, which is the same as the source file format you are working with. For us (people using VS), it's generally set to GB2312. Again, of course, the encoding depends on how the source file is encoded. If the file encoding is already UTF-8, but you also set it to GB2312, then Doxygen will UTF-8 as ANSI again UTF-8 conversion, naturally will be wrong.

Finally, the problem is often encountered is the Doxygen generated CHM file on the left of the tree directory of Chinese into garbled. This simply modifies the encoding type of the CHM index to GB2312. Enter GB2312 in the chm_index_encoding of the HTML. However, this method, there is a flaw in the CHM search page search results displayed in the Chinese text has become garbled. This is because Doxygen opens the HTML Help Workshop's Full-text search full-text searching option by default, and he should open the file and then search by ANSI in Full-text search (data indicates that HHW does not support UTF-8, Only iso-8859-1 or windows-1252 encodings are supported. and Doxygen generation of the right interface is UTF-8, which naturally appears to be a problem. In this case to do full-text search, in theory can only search English.

Our solution can only be recompile Doxygen code, in order to meet the search, as long as the right page file is not UTF-8. We first modify the code that writedefaultheaderfile this function to charset=gb2312 it. Then modify M_toutf8 = (void*)-1 in the constructor of Translatordecoder, the final conversion function when masking text is written. Finally, delete the input_encoding settings or enter UTF-8. This will make Doxygen think our text is UTF-8, so that we don't have to convert. The build replaces the original Doxygen.

Also need to add that there is another option is not to modify the source code of the author, but need to doxygen generated to the right of the HTML file using tools (such as Iconv) manually converted to GB2312, and then use HTML Help Workshop generation, the Internet has an article introduced, I test it, and there is no problem.

Finally, Doxygen is an open source project and supports the VS2005 project, so if you feel that it is not convenient, you can completely download the code and compile it yourself.

        So, you can basically generate beautiful documents with Doxygen. Code, Doxygen support a variety of format annotation style, according to manual choose their favorite is good.