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.