How to generate CHM with Doxygen and HTML Help Compiler?

Question

The short story: I can generate a CHM file with Doxygen. Launching the CHM file, I observe that the Contents and Index tabs do list the pages, namespaces, classes, and members of those classes. However, clicking on the items in those Contents and Index lists do not display any content.

I am on a computer using Windows 7 Professional SP1, 64-bit.

I use Doxywizard to run Doxygen version 1.8.9.1 on my code. It correctly generates the HTML output; the pages, namespaces, classes, and members appear in the documentation.

I then further want to convert the HTML into a compressed HTML (CHM) file.

I downloaded the Microsoft HTML Help Workshop version 1.31 (i.e., htmlhelp.exe version 4.74.8703 ) from the Microsoft website ( https://msdn.microsoft.com/en-us/library/windows/desktop/ms669985(v=vs.85).aspx ). I ran the installer. As the installer was proceeding, a popup message appeared:

This computer already has a newer version of HTML Help.

However, installation completed successfully. And, the hhc.exe program is there where I told it to install.

I now specify these relevant Doxygen settings:

• Wizard --> Output:
  • HTML is checked
  • "prepare for compressed HTML (.chm)" option is selected.
• Expert --> HTML:
  • GENERATE_HTMLHELP = YES
  • CHM_FILE = Foo.chm
  • HHC_LOCATION = C:\Program Files(x86)\Microsoft\HTML Help Workshop\hhc.exe

When I run Doxygen again, it reports an error:

error: failed to run html help compiler on index.hhp

The Foo.chm file is generated where expected. But, as described above, it is missing a lot of content.

I tried running hhc.exe manually on the HHP file generated by Doxygen. It does not indicate any errors.

C:\Program Files (x86)\Microsoft\HTML Help Workshop>hhc c:\test\html\index.hhp
Microsoft HTML Help Compiler 4.74.8702

Compiling c:\test\html\Foo.chm

Compile time: 0 minutes, 3 seconds
292     Topics
3,855   Local links
83      Internet links
0       Graphics

Created c:\test\html\Foo.chm, 259,580 bytes
Compression decreased file by 1,077,915 bytes.

However, the result is the same: a Foo.chm file that is missing content.

I subsequently found that I had another installation of the HTML Help Workshop on my computer. But, the hhc.exe was the exact same version. So, that is not likely the problem.

Can you suggest what else I can try to get all the documentation content to display in the CHM file?

Solution 1

The essential problem was that the CHM file was on a mapped network drive.

When I copied the CHM file to a physical drive on my computer, all the content displays.

Solution 2

When I have seen this problem (the html exists and the chm has content but that content is not visible), it has been because windows security has "blocked" the chm file. To see if this is what you are encountering try the following:

1. From windows explorer, Right click the generated .chm file and select properties.
2. On the General tab, if you see an Unblock button, click it.
3. Close the dialog and open the .chm file.

(I have not encountered this problem with locally generated doxygen .chm files, but I am hopeful from your description that this may fix your problem.)

Solution 3

In your doxyfile, put the path to hhc.exe in double quotes, since it contains spaces.

Or even better, do not use paths with spaces.

Comments

[Mike Finch]

I did not see a "blocked" button to click. But, that got me thinking on the right track. I had simplified my above problem description, by saying that the resulting Foo.chm file was on the c: drive. However, it is actually on a mapped network drive. When I copied the CHM file to a physical drive on my computer, all the content displayed. Problem solved. Thanks.