RF+NF: improving generated by epydoc documentation

* Adjusted description of PyMVPA module at top level
* Trying to figure out proper/good way to generate documentation.
* Added option to profiler to dump pstat file so epydoc could use it
* Adjusted epydoc.conf and Makefile to generate profile file and use
  it while creating documentation

Makefile

@@ -1,11 +1,13 @@
+PROFILE_FILE=tests/main.pstats
+
 all:
 
 distclean:
 	-@rm -f MANIFEST Changelog
 	-@rm -f mvpa/clf/libsvm/*.{c,so} \
 		mvpa/clf/libsvm/svmc.py \
 		mvpa/clf/libsvm/svmc_wrap.cpp \
-		tests/*.{prof,kcache}
+		tests/*.{prof,pstats,kcache} $(PROFILE_FILE)
 	@find . -name '*.pyc' -o -iname '*~' -o -iname '#*#' | xargs -l10 rm -f
 	-@rm -rf build
 	-@rm -rf dist
@@ -16,9 +18,12 @@ distclean:
 manual:
 	cd doc/manual && pdflatex manual.tex && pdflatex manual.tex
 
-apidoc:
+apidoc: $(PROFILE_FILE)
 	epydoc --config doc/api/epydoc.conf
 
+$(PROFILE_FILE): tests/main.py
+	@cd tests && ../tools/profile -K  -O ../$(PROFILE_FILE) main.py
+
 pylint:
 	pylint --rcfile doc/misc/pylintrc mvpa
 

doc/api/epydoc.conf

@@ -131,7 +131,7 @@ dotpath: /usr/bin/dot
 
 # The name of one or more pstat files (generated by the profile
 # or hotshot module).  These are used to generate call graphs.
-pstat: profile.out
+pstat: tests/main.pstats
 
 # Specify the font used to generate Graphviz graphs.
 # (e.g., helvetica or times).

mvpa/__init__.py

@@ -6,7 +6,36 @@
 #   copyright and license terms.
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
-"""MultiVariate Pattern Analysis"""
+"""MultiVariate Pattern Analysis
+
+
+Package Organization
+====================
+The epydoc package contains the following subpackages and modules:
+
+.. packagetree::
+   :style: UML
+
+:group Basic Data Structures: datasets
+:group Miscellaneous: misc
+
+:author: `Michael Hanke <michael.hanke@gmail.com>`__
+:requires: Python 2.4+
+:version: XXX
+:see: `The PyMVPA webpage <http://XXX>`__
+:see: `GIT Repository Browser <http://git.debian.org/?p=pkg-exppsy/pymvpa.git;a=summary>`__
+
+:license: The MIT License
+:copyright: |copy| 2006-2007 Michael Hanke <michael.hanke@gmail.com>
+
+:newfield contributor: Contributor, Contributors (Alphabetical Order)
+:contributor: `Yaroslav Halchenko  <mailto:debian@onerussian.com>`__
+
+.. |copy| unicode:: 0xA9 .. copyright sign
+"""
+
+__docformat__ = 'restructuredtext'
+
 
 if not __debug__:
 # TODO: psyco should be moved upstairs anyways

tests/main.py

@@ -44,8 +44,7 @@
     exec 'import ' + t
 
 
-if __name__ == '__main__':
-
+def main():
     # load all tests suites
     suites = [ eval(t + '.suite()') for t in tests ]
 
@@ -55,3 +54,6 @@
     # finally run it
     unittest.TextTestRunner().run( ts )
 
+if __name__ == '__main__':
+    main()
+

tools/profile

@@ -30,6 +30,7 @@ if __name__ == "__main__":
     displaykcachegrinder = True
     printstats = False
     pfilename = None
+    pstatsfilename = None
     profilelines = True
     profilelevel = 10                   # how many most hungry to list in stats
     run = True                          # either to run profiling at all
@@ -57,6 +58,9 @@ if __name__ == "__main__":
         elif sys.argv[0] in ["-o", "--output-file"]:
             pfilename = sys.argv[1]
             sys.argv.pop(0)
+        elif sys.argv[0] in ["-O", "--output-statsfile"]:
+            pstatsfilename = sys.argv[1]
+            sys.argv.pop(0)
         elif sys.argv[0] in ["-s", "--stats"]:
             printstats = True
             verbose(2, "Enabling printing stats")
@@ -120,13 +124,16 @@ if __name__ == "__main__":
 
         verbose(2, "Closed profiler")
 
-    if printstats:
+    if printstats or pstatsfilename:
         import hotshot.stats
         verbose(1, "Loading profile file to print statistics")
         stats = hotshot.stats.load(pfilename)
-        stats.strip_dirs()
-        stats.sort_stats('time', 'calls')
-        stats.print_stats(profilelevel)
+        if printstats:
+            stats.strip_dirs()
+            stats.sort_stats('time', 'calls')
+            stats.print_stats(profilelevel)
+        if pstatsfilename:
+            stats.dump_stats(pstatsfilename)
 
     kfilename = pfilename + ".kcache"
     if convert2kcache: