|
DoxyPress
1.7.0
|
DoxyPress indexes your source code to make it easier to navigate and find what you are looking for. There are also situations where you may want to search for something by keyword rather than browse for it. HTML browsers by default have no search capabilities which work across multiple pages, so either DoxyPress or external tools can be used to provide this functionality.
DoxyPress has multiple ways to add searching to the HTML output, each of which has its own advantages and disadvantages:
The easiest way to enable searching is to enable the built in client side search engine. This engine is implemented using JavaScript and DHTML only and runs entirely on the clients browser. So no additional tooling is required to make it work.
To enable it set html-search to YES in the project file and ensure search-server-based is set to NO.
An additional advantage of this method is that it provides live searching, i.e. the search results are presented and adapted as you type.
This method also has its drawbacks since it is limited to searching for symbols. It does not provide full text search capabilities and it does not scale well to very large projects.
If your HTML documentation will be hosted on a web server and the web server supports PHP, you can use the DoxyPress built in server side search engine.
To enable this set both html-search and search-server-based to YES in the project file and set search-external to NO.
Advantages over the client side search engine are that it provides full text search and it scales well to medium side projects.
Disadvantages are that it does not work on local files and does not provide search auto completion.
DoxyPress can generate the raw data which can be searched and leaves it up to external tools to do the indexing and searching. This allows developers the opportunity to use any indexer and search engine.
To use external searching set html-search, search-server-based, and search-external to YES in your project file.
Advantages over standard Server Side Searching are that this method may scale better with very large projects. It is also possible to combine multiple DoxyPress projects and external data into one search index. The way the interaction with the search engine is done, makes it possible to search from local HTML pages. Also the search results have better ranking and show context information if available.
Refer to External Searching for additional information.
If you are running DoxyPress on Windows you can generate compiled HTML Help file (.chm) from the DoxyPress HTML output. This is a single file containing all of the HTML files plus a search index. There are viewers for this format on many platforms and Windows supports it natively.
To enable this format set generate-chm to YES in your project file.
For DoxyPress to compile the HTML Help file, specify the path to the HTML compiler (hhc.exe) using the hhc-location tag and the name of the resulting CHM file using chm-file.
An advantage of this method is a single output file. Another advantage is full text search.
Disadvantages are that compiling the CHM file only works on Windows and requires Microsoft's HTML compiler, which is not actively supported.
If you are running DoxyPress on Mac OS X then you can make a "doc set" from the DoxyPress HTML output. A doc set consists of a single directory with a special structure containing the HTML files along with a precompiled search index. A doc set can be embedded in Xcode, which is the integrated development environment provided by Apple.
To enable the creation of doc sets set generate-docset to YES in the project file.
After DoxyPress has generated the HTML, a Makefile will be created in the HTML output directory. Running "make install" on this Makefile will compile and install the doc set.
Advantage of this method is that it nicely integrates with the Xcode development environment allowing users to click on an identifier in the editor and jump to the corresponding section in the DoxyPress documentation.
Disadvantage is that it only works in combination with Xcode on OS X.
The Qt application framework includes a program called Qt Assistant. This is a help viewer for Qt Compressed Help files (.qch).
To enable this feature set generate-qthelp to YES in your project file. Review the other Qt help related options such as qhp-namespace, hhc-location, and qhp-virtual-folder.
The Qt compressed help feature is comparable with the CHM output with the additional advantage that compiling the QCH file is not limited to Windows.
The disadvantage is the requirement to distribute the Qt Help Assistant with your documentation.
DoxyPress generated documentation can be embedded in Eclipse as a help plugin. The documentation will appear as a topic in the help browser, which can be started from "Help contents" in the Help menu. Eclipse will generate a search index for the documentation when you first search for a keyword.
To enable the help plugin set generate-eclipse to YES, and define a unique identifier for your project via eclipse-doc-id.
GENERATE-ECLIPSE = YES ECLIPSE-DOC-ID = com.yourcompany.yourproject
You will need to create a sub-directory called com.yourcompany.yourproject in the Eclipse plugin directory. Copy the DoxyPress output to the new sub-directory and then restart Eclipse.
1.7.0 
