Doxygenate

Doxygenation: Auto VisIt Source Docs

VisIt's coding guidelines outline standard documentation practices that facilitate auto-generated code documentation. We are currently revamping our ability to automatically translate our comment format into doxygen supported comments and auto-gen doxygen html docs.

The tool to accomplish this is comprised of a set of python scripts located in the source code tree at:

src/tools/doxygenate/

Current Features

• Identifies the following VisIt comment elements:
  • Creation
  • Purpose
  • Programmer
  • Notes
  • Arguments
  • Modification Lists

Getting Started

• Obtain/Build/Install Doxygen
• Obtain/Build/Install Graphviz (for the dot tool)
• Make sure both doxygen and dot are in your shell path.
• Doxygenate the source tree and prepare the Doxyfile by running:

./doxygenate.py ~/path/to/trunk/src/ output

(Note: In its current form this script needs to be run in src/tools/doxygenate to import DocBlock.py and obtain the title page (Index.doxy) and skeleton Doxyfile (Doxyfile.in))
(Also note: Since doxygenate operates recursively on the src directory, it is CRITICAL that the "output" directory be outside the src directory tree)

• Run doxygen:

 doxygen

• Open the resulting docs

firefox output/doxyout/html/index.html

Todo

• Populate the title page
• Verify auto-grouping (avt/engine/viewer,etc)
• Improved CSS?

Current Hiccups

• Some class carts have double inheritance lines.
• Stray characters due to block parsing errors.

If you encounter anything strange please post a link to it here so we can address it.