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 CMakeLists.txt file, which would make it
    a part of the CMake build system.  (It also uses gnumake-specific
    syntax, which may violate portability.)  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:

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