How to Regenerate the Torque Engine Reference

Introduction

One of the beauties of using Doxygen to document Torque is that it's very easy to update the documentation to reflect changes in the engine. If something is added, removed, or changed, all you need is the Torque source code, a few freely available software tools, and you can make a new copy of the docs.

Note:
This documentation is considered part of Torque and therefore MAY NOT BE DISTRIBUTED TO NON-LICENSE HOLDERS, under the terms of the TGE license agreement (see section 3c of the license at http://www.garagegames.com/pg/product/eula.php?id=28). If you regenerate this documentation, you MUST take steps to prevent non-licensees from accessing it. The suggested route is to keep your regenerated copies of this documentation on your local system.

What You'll Need

You will need the following tools to regenerate the documentation in HTML:

How To Regenerate

Regenerating the docs is a matter of running doxygen at the root of your Torque install, and passing it the path to your doxygen configuration file. For example, I have a file called doc.bat in the root of my Torque checkout, which contains:

"c:\Program Files\doxygen\bin\doxygen.exe" doc\doxygen\html\doxygen.html.cfg

And that's all you need to do to regenerate - though you'll want to tweak your doxygen.html.cfg file to reflect your individual setup. The configuration lines you care about are:

  • PROJECT_NAME, if you want to indicate that these docs aren't for stock Torque. (For instance, setting it to "Secret Torque Project")
  • OUTPUT_DIRECTORY, this controls where docs are placed.
  • STRIP_FROM_PATH, which contains a path to strip from file names in the docs. For instance, my copy of Torque HEAD lives in c:/torque/HEAD, so I set STRIP_FROM_PATH to that so I only see engine//console//console.h, instead of a full path.
  • EXCLUDE, contains some regular expressions which will be used to filter out paths. The config file by default filters out CVS directories and tries to exclude the Carbon and Unix platform libraries.

More in-depth information is available at http://www.doxygen.org/, on the manual pages.