HvD: Added some experimental scripts for source code documentation generation.

At the moment this topic is wide open.

Doxygen seems to be the more popular tool (in particular among C-programmers)
and it puts more effort in to generate documentation. However on a code as 
large as NWChem it suffers from segmentation faults.

Robodoc simply extracts documentation from the source code comments. Hence it
is more limited in its ability to extract information when the code hasn't been
commented. However, as an advantage I haven't seen it crash on NWChem yet.

The main reason for checking this stuff in a this point is that we ship it
with the development tar-balls and if something does not work we can tell 
people how they can reproduce the problems we are hitting. Alternatively,
this allows developers to play with this stuff as well. However, anyone playing
with this must consider that we may choose another tool (or no tool at all)
as some point in the future. Hence putting a lot of work into the documentation
at this point is unwise.

contrib/doxygen/README

@@ -0,0 +1,22 @@
+DOXYGEN README
+==============
+
+This directory contains experimental material to generate source code
+documentation using Doxygen. 
+
+To generate the source code documentation run
+
+	cd $NWCHEM_TOP
+	./contrib/docygen/run_doxygen
+
+After this $NWCHEM_TOP/srcdoc/html should contain the source code documentation.
+At the moment very few files of NWChem have been provided with the appropriate
+comments. Hence the Doxygen documentation essentially only contains what
+the tool can extract from the source code itself.
+
+More information on Doxygen can be found at:
+
+ - http://www.stack.nl/~dimitri/doxygen
+
+Experience so far has shown that the tool cannot easily cope with a code as
+large as NWChem. 

contrib/doxygen/run_doxygen

@@ -0,0 +1,16 @@
+#!/bin/bash
+#
+# Doxygen run script for NWChem
+#
+# Doxygen is a source code documentation tool. It interprets and analyses
+# the source code and writes a substantial chunk of documentation. The 
+# documentation can be enriched by providing more details in comment lines.
+# Doxygen is the defacto standard approach to documenting C-code. 
+#
+# Experience on NWChem so far has shown that this is challenging with 
+# Doxygen generating many error messages and even seg-faulting.
+#
+# This script has been designed to be run in the $NWCHEM_TOP directory,
+# and producing a directory with documentation in $NWCHEM_TOP/srcdoc.
+#
+doxygen ./contrib/doxygen/doxygen.rc

contrib/robodoc/README

@@ -0,0 +1,24 @@
+ROBODOC README
+==============
+
+This directory contains experimental material to generate source code 
+documentation using Robodoc.
+
+To generate the source code documentation run
+
+	cd $NWCHEM_TOP
+	./contrib/robodoc/run_robodoc
+
+After this $NWCHEM_TOP/srcdoc.html should contain the source code documentation
+of all of NWChem. As currently very few (i.e. no) files contain the appropriate
+comments that Robodoc recognizes this file will be small.
+
+Experience so far has shown Robodoc to be stable and capable to handle a 
+large code. How the tool will behave if a large fraction of the source code
+is documented is unknown.
+
+For more details on Robodoc see:
+
+ - http://sourceforge.net/projects/robodoc/       -- project pages
+ - http://www.xs4all.nl/~rfsber/Robo/robodoc.html -- general info
+

contrib/robodoc/robodoc.rc

@@ -0,0 +1,102 @@
+# Robodoc configuration file for the documentation of DL-FIND
+#
+items:
+    NAME
+    FUNCTION
+    SYNOPSIS
+    INPUTS
+    OUTPUTS
+    COMMENTS
+    DATA
+    SIDE EFFECTS
+    HISTORY
+    BUGS
+    COPYRIGHT
+    PORTABILITY
+ignore items:
+    HISTORY
+    BUGS 
+    COPYRIGHT
+    SOURCE
+item order:
+    NAME
+    SYNOPSIS
+    INPUTS
+    OUTPUTS
+    FUNCTION
+source items:
+    SYNOPSIS
+    INPUTS
+    OUTPUTS
+preformatted items:
+    DATA
+format items:
+    FUNCTION
+    SIDE EFFECTS
+options:
+    --src src
+    --doc srcdoc
+    --html
+#   --nosort
+    --singledoc
+    --sections
+    --index
+    --toc
+    --tabsize 8
+    --syntaxcolors
+    --documenttitle "NWChem Source Documentation"
+    --nopre
+#   --css contrib/robodoc/robodoc.css
+headertypes:
+    J  "Projects"          robo_projects    2
+    F  "Files"             robo_files       1
+    e  "Makefile Entries"  robo_mk_entries
+    x  "System Tests"      robo_syst_tests
+    q  Queries             robo_queries
+ignore files:
+    README
+    CVS
+    .svn
+    *.bak
+    *~
+    "a test_*"
+accept files:
+    *.f90
+    *.f
+    *.fh
+    *.F
+    *.c
+header separate characters:
+    ,
+header ignore characters:
+    [
+remark markers:
+    c
+    *
+remark begin markers:
+    /*
+remark end markers:
+    */
+header markers:
+    ****
+    c****
+end markers:
+    ******
+    c******
+source line comments:
+    //
+keywords:
+    if
+    else
+    end
+    do
+    end do
+    enddo
+    select
+    end select
+    case
+    while
+    for
+    subroutine
+    function
+    call

contrib/robodoc/run_robodoc

@@ -0,0 +1,32 @@
+#!/bin/bash
+#
+# Designed to use Robodoc 4.99.38
+#
+# Robodoc still seems to change non-trivially so the robodoc.rc
+# and the default behaviors might produce unexpected results when
+# used with different versions of robodoc.
+#
+# See also:
+# - http://sourceforge.net/projects/robodoc/       -- project pages
+# - http://www.xs4all.nl/~rfsber/Robo/robodoc.html -- general info
+#
+#
+#
+# The include directory contains header files that duplicate some
+# of the information that Robodocs extracts from the same header files
+# in the source code directories. To suppress duplicates from the
+# Robodoc generated documentation we deny access to the include 
+# directory.
+#
+chmod 000 src/include
+#
+# Now we run Robodoc to generate the documentation. Note that all the
+# settings are retrieved from the robodoc.rc file. The settings are
+# based on the expectation that Robodoc runs in the $NWCHEM_TOP
+# directory.
+#
+robodoc --rc contrib/robodoc/robodoc.rc
+#
+# Restore normal access privileges to the include directory.
+#
+chmod 750 src/include