Tools | Doxygen

Doxygen

Doxygen Home

Officially-supported version in Trilinos: 1.7.4

Overview

Doxygen is a program for generating documentation from source files. It allows developers to easily maintain consistent, up-to-date documentation because the code and comments reside in the same file. The documentation generated by Doxygen can then by posted online for easy access. This approach satisfies both the specification and the design requirements in the case of object-oriented engineering of mathematical software.

Doxygen in Trilinos

Doxygen is used by most Trilinos packages as a way to maintain up-to-date documentation of the code by keeping documentation and source in the same files. Using Doxygen in Trilinos is also very simple, since the Trilinos Framework provides a number of services and defaults to individual packages that minimize the amount of work any package needs to do.

The "build_docs" Script

In the "doc" directory of every Trilinos package, there is an executable file called "build_docs". Any actions necessary for creating that package's documentation should be contained therein. Defining this one, single place for the creation of documentation allows both for package flexibility and global services. The build_docs script for most packages only needs to contain the single command: "doxygen Doxyfile", though it could include many more commands, if needed.

Doxygen Defaults

There is a file located at "Trilinos/packages/common/" named "Doxyfile" that contains reasonable defaults for all packages. To make use of these defaults, all a package has to do is to include it at the top of their own Doxyfile and then override or append to any option they need changed. Note that the defaults may be slightly different depending on the branch. It is the policy that source browsing needs to be turned off in the development branch, but can be left on in the release branches.

Contents of "PACKAGE/doc" Directory

The "doc" directory for most packages contains files from many different generations of documentation systems. Ideally, all files not needed by any commands given in the build_docs script should be removed from the repository to minimize confusion. In particular, many packages already had a file named "Doxyfile" when the current documentation system was put in place. Instead of overwriting files that were potentially still used, a file name "DoxyfileWeb" was created for each package. For many packages this is the only Doxyfile being used. If this is the case, it should be renamed to the default "Doxyfile", the command in build_docs should be changed accordingly, "DoxyfileWeb" should be removed from the repository and any other unused files should be removed as well.

Placement of Generated Documentation

For Trilinos-wide services to locate generated documentation, it must be located anywhere underneath "Trilinos/packages/PACKAGE/", be contained in a directory named "html" which includes a file named "index.html".

Documentation on Package Website

When documentation is generated for the package websites, a script descends into each "Trilinos/packages/PACKAGE/doc" directory and executes "build_docs". Then, the entire contents of any directory named "html" and containing a file named "index.html" are copied to the web space within an otherwise empty, but analogous directory structure. The top-level documentation page that is linked to by default (for each branch) is the one located at "Trilinos/packages/PACKAGE/doc/html/index.html" (within the given branch). Not all packages have documentation for all releases. To change which releases your package website displays documentation links to, simply open "TrilinosWeb/version3/packages/PACKAGE/header.php and change the argument to "setIncludeReleaseXXDocs()" to either "true" or "false".

Generating Documentation Locally

To generate the documentation for any given package locally, simply descend into the doc directory for that package, run the build_docs script, and open "PACKAGE/doc/html/index.html" in your browser. To generate local documentation for all Trilinos packages, simply go to "Trilinos/doc" and run "build_docs.pl". This will generate the documentation for all packages and create a file named "index.html" in "Trilinos/doc" with links to each package's documentation.

Version Issues

Different versions of Doxygen documentation are extracted from the different Trilinos release branches. To avoid confusion, these should all set the Doxygen PROJECT_NUMBER property to clearly identify both the package version number and the Trilinos release version--for example: "Epetra 3.4 in Trilinos 6.0" or "Epetra 3.5d in Trilinos Development Branch". Also, take care to ensure that the package release number is consistent between the Doxyfile, the package-level configure.ac, the version number routing (usually *version.h), and the bugzilla database.

Release Tarball Issues

Make sure that any files you would like to make it into the release tarball for a given branch are included in EXTRA_DIST in your package's Makefile.am. See [Verifying the Contents of the Distribution Tarball] (https://software.sandia.gov//trilinos/developer/sqp/dist_tarball.html) for more information.