The purpose of this directory is to provide a set of automatically-
generated swig interface files that in turn provide docstrings for the
swig-generated python wrappers that comprise PyTrilinos.  The
generation of these swig interface files requires doxygen, which I do
not wish to impose as a prerequisite on users.  Therefore, these swig
interface files (Teuchos_dox.i, Epetra_dox.i, ...) are included as
part of the repository, and ultimately the distribution tarball, even
though they can be generated automatically.

Here is how the PyTrilinos automated documentation system works:

  * For each package, Teuchos, Epetra, etc., there is a corresponding
    doxygen configuration file in this directory: Doxyfile_Teuchos,
    Doxyfile_Epetra, etc.

  * These local doxygen configuration files produce only XML output of
    the doxygen-style documentation for each package, putting their
    results in a local directory with the corresponding package name
    (Teuchos/, Epetra/, etc.).

  * The python script doxy2swig.py is used to convert the generated
    XML (Teuchos/index.xml, Epetra/index.xml, etc.) into a swig
    interface file with a series of %feature("docstring") directives.
    These swig interface files are named Teuchos_dox.i, Epetra_dox.i,
    etc.

  * The above steps are controlled by a local Makefile that is for
    developer use only.  Therefore, it is just a plain-vanilla
    Makefile, as opposed to a Makefile.am, which would make it a part
    of the autotools build system.  (It also uses gnumake-specific
    syntax, which violates an autotools assumption.)  It is the
    responsibility of the developer to ensure that the swig
    documentation files (Teuchos_dox.i, Epetra_dox.i, etc.) are up-to-
    date.  Because the swig documentation files are both stored in the
    repository, and generated by the Makefile, getting dependencies to
    work is a little tricky.  The recommended method is for developers
    to invoke

      $ make depend
      $ make

  * The PyTrilinos swig interface files (../src/Teuchos.i,
    ../src/Epetra.i, etc.) may then employ the %include directive to
    include the appropriate swig documentation file (Teuchos_dox.i,
    Epetra_dox.i, etc.).  The resulting generated python functions,
    classes and methods will then be given appropriate doxygen
    docstrings.

To add documentation support for a new package (named Package, for
example) to this directory, follow these steps:

  * Copy an existing Doxyfile to Doxyfile_Package and modify it
    appropriately.

  * Modify the Makefile so that variable PACKAGES includes the new
    package name.

  * Create Package_dox.i:

      $ make depend
      $ make Package_dox.i

  * Add files to the repository:

      $ cvs add Doxyfile_Package Package_dox.i
      $ cvs commit -m "Added support for Package documentation"

  * Add the doc/Doxygen/Package_dox.i file to the list of EXTRA_DIST
    in ../../Makefile.am.  This ensures that the documentation swig
    interface file makes it into release tarballs.

