Index: src/documentation/userinterfaces/python.dox
===================================================================
--- src/documentation/userinterfaces/python.dox	(revision f281c570d3846adae28ef56f504a320da69c7929)
+++ src/documentation/userinterfaces/python.dox	(revision f281c570d3846adae28ef56f504a320da69c7929)
@@ -0,0 +1,99 @@
+/*
+ * Project: MoleCuilder
+ * Description: creates and alters molecular systems
+ * Copyright (C)  2010 University of Bonn. All rights reserved.
+ * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
+ */
+
+/**
+ * \file python.dox
+ *
+ * Created on: Nov 01, 2011
+ *    Author: heber
+ */
+
+/**
+ * \page userinterfaces-python Python module
+ *
+ *  Via boost::python all of Molecuilder Action's are exported into a python
+ *  module such that all functionality can also be directly used in a python
+ *  script.
+ *
+ *  This is done in \bsrc/Actions/pyMoleCuilder.cpp.
+ *
+ *  There again some preprocessor magic is happening. One the one hand we
+ *  need GlobalListOfActions.hpp to have a list of all actions available.
+ *  Second, in AllActionPython.hpp we define export functions for every
+ *  Action (in essence we use the COMMAND function, see Action_impl_pre.hpp,
+ *  which makes an Action usable internally as a normal function).
+ *
+ *  Then, at the beginning of the BOOST_PYTHON_MODULE declaration we initialize
+ *  the ActionHistory (same as in main() in builder.cpp), and on exit we
+ *  perform cleanUp() via the atexit() hook to make sure that everything
+ *  is not only removed but more importantly in the correct orders. This is
+ *  required because we use many static elements which have to be deinitialized
+ *  in the correct sequence as they depend on one another.
+ *
+ *  \section userinterfaces-python-first-test A first test script
+ *
+ *  A small python test script would then look like this:
+ *  \code
+ *  import pyMoleCuilder as mol
+ *  mol.WorldInput("test.xyz")
+ *  mol.SelectAtomById(0)
+ *  mol.AtomRemove()
+ *  \endcode
+ *  which loads a file \b test.xyz into the (internal) World, selects the first
+ *  atom and removes it.
+ *
+ *  \section userinterfaces-python-running Running a test script
+ *
+ *  In most cases however, python cannot find the library (except molecuilder
+ *  has been installed in some system-default folder). In this case you should
+ *  prefix your call to the python interpreter with:
+ *  \code
+ *  PYTHONPATH="<buildpath>/src/.libs" python
+ *  \endcode
+ *  where \a <buildpath> is the top build directory of molecuilder. If you have
+ *  installed molecuilder (\code make install \endcode), but the
+ *  \a <installpath> (i.e. the \a prefix given at to the configure call) is non-
+ *  standard, then prepend this
+ *  \code
+ *  PYTHONPATH="<installpath>/share/site-packages" python
+ *  \endcode
+ *
+ *  \section userinterfaces-python-notes Some notes to keep in mind
+ *
+ *  \subsection userinterfaces-python-notes-cleanup Cleaning up or reset state ...
+ *
+ *  Whenever you need to reset the internal state of the molecuilder, i.e.
+ *  you want to save the current file and work on something new, use
+ *  \code
+ *  mol.cleanUp()
+ *  \endcode
+ *  This frees all memory, removes all static instances on the heap, and saves
+ *  your input file (\sa WorldInputAction).
+ *
+ *  \subsection userinterfaces-python-help Help inside the interpreter
+ *
+ *  Note that the pyMoleCuilder module is fully documented. I.e.
+ *  \code
+ *  import pyMoleCuilder as mol
+ *  help(mol)
+ *  \endcode
+ *  gives you a complete list of present functions/Actions in the module
+ *  including their signature and a brief description (this is all
+ *  automatically generated via the proprocessor magic from the Action's
+ *  \b .def files).
+ *
+ *  Likewise you may obtain help on each single function, e.g.
+ *  \code
+ *  import pyMoleCuilder as mol
+ *  help(mol.WorldInput)
+ *  \endcode
+ *  gives you the docu string on WorldInputAction.
+ *
+ *
+ * \date 2011-11-01
+ *
+ */
Index: src/documentation/userinterfaces/userinterfaces.dox
===================================================================
--- src/documentation/userinterfaces/userinterfaces.dox	(revision 35a88927d82713a677dde8bd7c3df3ce9e9ba429)
+++ src/documentation/userinterfaces/userinterfaces.dox	(revision f281c570d3846adae28ef56f504a320da69c7929)
@@ -16,5 +16,5 @@
  * \page userinterfaces User Interfaces
  *
- *  MoleCuilder has three interfaces at your disposal:
+ *  MoleCuilder has four interfaces at your disposal:
  *  -# \ref userinterfaces-textmenu  A simple interactive console-based menu,
  *    where awaits your choices and inputs in order to set atoms
@@ -26,4 +26,6 @@
  *    display the molecular structure being built and lots of other
  *               informations to ease the construction of bigger geometries.
+ *  -# \ref userinterfaces-python Molecuilder's functionality is available as a
+ *    python module to be used in python scripts
  *
  *  Note that all user interfaces are created via a common way that is
