some more work on Sphinx

use python doc/make.py to create the documentation

git-svn-id: https://dng.biozentrum.unibas.ch/svn/openstructure/trunk@2326 5a81b35b-ba03-0410-adc8-b2c5c5119f08

doc/make.py

+import os, sys
+import shutil
+if len(sys.argv)==2:
+  root_dir=sys.argv[1]
+else:
+  root_dir='.'
+
+def _OutputPath(inpath, outdir):
+  parts=inpath.split(os.path.sep)
+  filtered_parts=[outdir]
+  index=parts.index('modules')
+  for part in parts[index+1:]:
+    if part!='doc':
+      filtered_parts.append(part)
+  return os.path.join(*filtered_parts)
+
+def _RequireCopy(in_name, out_name):
+  if not os.path.exists(out_name):
+    return True
+  if os.path.getmtime(in_name)>os.path.getmtime(out_name):
+    return True
+  return False
+def _MkDir(dirname):
+  """
+  Recursively create directories if they don't exist
+  """
+  parts=dirname.split(os.path.sep)
+  for i, d in enumerate(parts):
+    n=os.path.join(*parts[:1+i])
+    if not os.path.exists(n):
+      os.mkdir(n)
+
+def _CollectRstDocs(outdir, dirname, fnames):
+  for fname in fnames:
+    if fname.endswith('.rst'):
+      in_name=os.path.join(dirname, fname)
+      out_name=_OutputPath(in_name, outdir)
+      out_dir=os.path.dirname(out_name)
+      if not os.path.exists(out_dir):
+        _MkDir(out_dir)
+      if _RequireCopy(in_name, out_name):
+        print 'cp %s %s' % (in_name, out_name)
+        os.system('cp %s %s' % (in_name, out_name))
+      
+for sub_dir in ('modules',):
+  os.path.walk(sub_dir, _CollectRstDocs, 'doc/source')
+os.system('sphinx-build -b html -c %s %s %s' % ('doc/conf', 'doc/source', 
+                                                'doc/build'))
\ No newline at end of file

modules/doc/install.rst

+Installing OpenStructure
+================================================================================
+
+This document describes how to install OpenStructure from source. If you are not planning to develop code for OpenStructure, you might be better off with one of the binaries available for download.
+
+Installing the Dependencies
+--------------------------------------------------------------------------------
+
+OpenStructure uses a bunch of OpenSource libraries. If you haven't already installed them, please install them now!
+
+ * `CMake <http://cmake.org>`_
+ * `Eigen2 <http://eigen.tuxfamily.org>`_
+ * `Boost <http://boost.org>`_
+ * `libpng <http://www.libpng.org>`_
+ * `Python <http://python.org>`_
+ * `Qt <http://qt.nokia.com>`_
+
+When you enable support for image processing, you will need:
+
+ * `FFTW3 <http://fftw.org>`_. By default, OpenStructure is compiled with single precision and thus also requires FFTW to be compiled with single precision. Most platforms offer this as a second package. If you are compiling manually, use the `--enable-single` option.
+
+ * `libtiff <http://www.libtiff.org>`_
+
+
+
+If you would like to use the graphical user interface, also install:
+
+ * `SIP <http://www.riverbankcomputing.co.uk/software/sip/download>`_.
+ * `PyQt4 <http://www.riverbankcomputing.co.uk/software/pyqt/download>`_.
+
+In case you are compiling under Windows you have to install `Visualstudio
+2008 <http://www.microsoft.com/express/Downloads>`_. to compile the dependecies 
+and OpenStructure. We recommend to compile the dependecies manually. Enter the 
+directories where the dependencies are located in Tools->Options->Projects and 
+Solutions->VC++ directories. Choose 'bin' directories to enter program paths to 
+cmake, qmake and python, 'lib' directories to point to the location(s) of your 
+dependencies.
+
+Checking out the Source
+--------------------------------------------------------------------------------
+
+You can checkout the source from SVN. The repository is located at
+
+   https://dng.biozentrum.unibas.ch/svn/openstructure/trunk
+
+If you are using the commandline client, type in your shell 
+
+   svn co https://ost.biozentrum.unibas.ch/svn/openstructure/trunk
+
+On Windows install svn clients like `tortoisesvn <http://tortoisesvn.tigris.org>`_ and use the function 'checkout' then enter the above mention URL.
+
+
+Configuring
+--------------------------------------------------------------------------------
+
+
+OpenStructure uses `CMake <http://cmake.org>`_ for compiling and building the project. The next required step is to configure the build environment using cmake. You can do that by invoking `cmake` in the project directory (On Windows choose Tools->visualstudio commandline prompt from within visualstudio) :
+
+    cmake . <options>
+
+There are two kinds of options: Options that let you control the building behaviour, enabling and disabling the compilation of certain modules and options that let you tell CMake where to find the dependencies. All of them are passed to CMake with via `-D<opt>=<value>`.
+
+Flag to choose build system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On Windows make sure you specify -G"Visual Studio 9 2008"!
+
+Flags to Control the Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, `CMake <http://cmake.org>`_ searches the standard directories for dependencies. However, on some systems, this might not be enough. Here is a short description of how CMake figures out what dependencies to take and how you can influence it.
+
+ * Boost is mainly controlled via the `BOOST_ROOT` option. If boost wasn't
+   found, it should be set to the prefix of the boost installation.
+
+ * `QT_QMAKE_EXECUTABLE` defines the exact Qt installation to take. It should 
+   be set to the full path to `qmake`.
+ 
+ * `PYTHON_ROOT` is the Python equivalent of BOOST_ROOT. It should be set to 
+   the prefix path containing the python binary, headers and libraries.
+
+ * `SYS_ROOT` controls the general prefix for searching libraries and headers.
+   By default, it is set to `/`.
+
+Build Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * `ENABLE_UI` controls whether to build the graphical user interface module. By
+   default it is set to true. 
+ * `ENABLE_IMG` controls whether to build the image processing module. This will
+   enable support for density maps, and general image processing in 1, 2 an 3
+   dimensions. By default it is set to true. 
+
+ * `ENABLE_GFX` controls whether to build the graphics module. By default, this
+   is set to true. If set to none, this implies `ENABLE_UI=NO`.
+   
+ * Shader support is controlled with `USE_SHADER`. By default, no shaders are
+   used.
+   
+ * If `OPTIMIZE` is set to 1, an optimized version of OpenStructure is built.
+
+Building the Project
+--------------------------------------------------------------------------------
+
+Type `make`. If you are using a multi-core machine, you can use the `-j` flag to run
+multiple jobs at once.
+
+On Windows run 'Build OpenStructure' from the build menu.

modules/doc/intro.rst

+A gentle introduction to OpenStructure
+================================================================================
+
+In this tutorial you will be learning by example how to use the OpenStructure 
+framework. 
+
+We assume that you already have a version of OpenStructure installed. If not, 
+please refer to :doc:`install`.
+
+
+What will be covered in this tutorial?
+--------------------------------------------------------------------------------
+
+This tutorial is aimed at users that would like to get their hands dirty and 
+execute commands in Python and write scripts rather clicking their way through a 
+shiny user interface. The user interface of OpenStructure is in a very early 
+state anyway that you probably won't go far by clicking you way through...
+
+The first part of the tutorial is a walk-through of the basic functionality you 
+will be using in your everyday work. You will learn how to load structure 
+datasets, inspect, display them in the 3D window and save them. 
+
+
+Getting ready to rumble
+--------------------------------------------------------------------------------
+
+The files we will be using in the tutorial are available in the examples folder 
+that comes with OpenStructure. Depending on your platform, the examples are 
+located at a different location:
+
+ * on *MacOS X* the files are in /Applications/OpenStructure/Examples
+ * on *Linux* and *Windows* PREFIX/share/openstructure/examples, where PREFIX is 
+   the path to the directory containing OpenStructure.
+
+Starting DNG
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The graphical user interface of OpenStructure is called DNG (Dino/DeepView Next 
+Generation). To start it, 
+
+ * on *MacOS X* double click DNG.app in /Applications/OpenStructure
+ * on *Windows* double click dng.bat inside the PREFIX/bin directory
+ * on *Linux* fire up a terminal change into the OpenStructure installation 
+   directory and type 'bin/dng'. If you have the binary directory in the PATH, 
+   typing dng is sufficient.
+
+Interactive Python Shell
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now we will enter commands in the Python Shell (in the screenshot above, the 
+python shell is located at the bottom of the main window). If you want to get 
+more information on any object, function or class, the python help command may 
+be useful. For example:
+
+  .. code-block:: python
+
+    # get list of methods of EntityView
+    help(mol.EntityView)
+    # get help for method Select
+    help(mol.EntityView.Select)
+    
+Loading and inspecting a protein structure
+--------------------------------------------------------------------------------
+
+OpenStructure has a module that is dedicated to deal with input and output of 
+data, including sequence alignment formats, protein structures and density data 
+and images.  If you are reading this tutorial you most certainly have dealt with 
+protein structures before and you are most certainly aware that they are usually 
+stored in Brookhaven structure files (aka PDB files). The official name for 
+molecules stored in a PDB file is an entity. You will hear this word all the 
+time, but you can replace the word entity with molecule in your head.
+
+
+To load a PDB file, type
+
+  .. code-block:: python
+
+     fragment=io.LoadPDB('/path/to/examples/entity/fragment.pdb')
+
+This will load the fragment from the specified file 'fragment.pdb' and store the result in fragment. For more information on the LoadPDB function, type
+
+  .. code-block:: python
+  
+     help(io.LoadPDB)
+     
+Now let's inspect what we just loaded:
+
+  .. code-block:: python
+  
+     print fragment.chain_count
+     print fragment.residue_count
+     print fragment.atom_count
+
+As you can see, our fragment consists of one peptide chain of 12 amino acids and 
+has 81 atoms in total. Now let's examine our fragment in more detail. Enter the 
+command
+
+  .. code-block:: python
+  
+     for residue in fragment.residues:
+       print residue  
+
+This will print a list of all residues in the fragment. Similarly to get a list 
+of atoms, use:
+
+  .. code-block:: python
+  
+    for atom in fragment.atoms:
+      print atom
+
+Of course, we can also get a list of atoms grouped by residues:
+    
+  .. code-block:: python
+  
+    for residue in fragment.residues:
+      print residue, 'has', residue.atom_count, 'atom(s).'
+      for atom in residue.atoms:
+        print ' ', atom.name, atom.pos
+
+And, for completeness, we will first group them by chain, then by residues.
+
+  .. code-block:: python
+  
+    for chain in fragments.chains:
+      print 'chain', chain.name, 'has', chain.residue_count, 'residue(s)'
+      for residue in chain.residues:
+        print ' ', residue, 'has', residue.atom_count, 'atom(s).'
+        for atom in residue.atoms:
+          print '    ', atom.name, atom.pos
+
+Aah, wait! A protein fragment would not be complete without bonds: Let's see 
+what bonds we have in there:
+
+  .. code-block:: python
+  
+    for bond in fragment.bonds:
+      print bond
+      
+From these short code examples we already see how the entity is structured: On 
+one hand we have a hierarchy of chains, residues and atoms. On the other hand, 
+we have bonds that form a network overlayed on the hierarchy. This is 
+illustrated in the picture on the left. An important feature of entities is that 
+we can always assume that the hierarchy is intact. You will never find an atom 
+without residues, no residue can exist without a parent chain and chains belong 
+always to an entity. 
+
+Let There Be Shiny Graphics
+--------------------------------------------------------------------------------
+
+For visually inspecting the fragment, we now create a graphical representation 
+of the entity:
+
+  .. code-block:: python
+  
+     go=gfx.Entity("Fragment", fragment)
+     scene.Add(go)
+     scene.CenterOn(go)
+
+Now you will see the fragment in the 3D window (left):
+
+![](docs/tut/sel.png)
+
+Use the mouse to rotate, zoom in an shift the camera. Double clicking on an atom will center the camera on that atom. 
+
+Introduction to Views
+--------------------------------------------------------------------------------
+
+Often during processing and visualisation of data, only parts of a protein 
+structure are of interest. This realisation has had a major impact on the design 
+of OpenStructure and is tied very deeply into the core of the framework. 
+Subparts of structure are modeled as so-called :class:`EntityViews 
+<mol.EntityView>`. You can think of them as a selection of chains, residues, 
+atoms and bonds of an entity. A views has almost the same interface as the 
+underlying entity, making it very easy to mix entity views with handles in 
+Python due to the dynamic nature of the language. An algorithm that is written 
+for entities will almost always (with some care) also work for 
+:class:`EntityHandles <mol.EntityHandle>`. This is referred to as `duck-typing 
+<http://en.wikipedia.org/wiki/Duck_typing>`_ (I don' t care if it is a duck as 
+long as it looks like a duck), a concept used all over the place in Python. 
+
+A typical view can be seen in the image on the left. The view consists of one 
+chain, one residue and two atoms. Again the same rule applies: No atom can be 
+part of the view without it's residue. In this example, no bonds are included, 
+since there is at most one atom per bond in the original structure.
+
+To familiarize yourself with the concept of views, we will use the fragment in 
+the 3D window.
+
+We will use several ways to select parts of our fragment:
+ * By using a dedicated query language
+ * By manually constructing a view
+
+The Query Language
+--------------------------------------------------------------------------------
+
+The first way to select parts of a structure is with a dedicated mini-language, 
+called ["the query language”](docs/tut/query.html). In the Python Shell, type
+
+  .. code-block:: python
+  
+    go.selection=fragment.Select('')
+    
+A green halo will be displayed around the selected parts (image in the middle).
+
+As you can see the previous statement created a “full view”, containing all the 
+chains, residues, atoms and bonds. To select lysine residues, type
+
+  .. code-block:: python
+  
+    go.selection=fragment.Select('rname=LYS')
+    
+
+As you can see (image in the middle), the  only lysine residue is now 
+highlighted in the 3D window, because it was the only one matching the predicate 
+"residue name must be equal to LYS". Several such predicates can be combined 
+with boolean operators such as *and* and *or*. To select residues with residue 
+number 1 to 3, the following statement will do the job:
+
+  .. code-block:: python
+  
+    go.selection=fragment.Select('rnum>=1 and rnum<=3')
+    
+but this is very cumbersome. That's why there is a shortcut to this statement. 
+You can specify a range of values.
+
+  .. code-block:: python
+  
+    go.selection=fragment.Select('rnum=1:3')
+
+For a complete description of what you can do with the query language, have a 
+look at the :doc:`../mol/base/query`.
+
+
+Constructing Views Manually
+--------------------------------------------------------------------------------
+
+Sometimes the query language Is Not Enough (TM). For these cases the 
+construction of manual entities becomes neccessary. This is pretty straight 
+forward:
+
+  .. code-block:: python
+  
+    view=fragment.CreateEmptyView()
+    ca=fragment.FindAtom('A', mol.ResNum(1), 'CA')
+    cb=fragment.FindAtom('A', mol.ResNum(1), 'CB')
+    view.AddAtom(ca)
+    view.AddAtom(cb)
+    go.SetSelection(view)
+
+The last step sets our constructed view as the current selection, displaying it 
+in the 3D window. As you can see, C-alpha and C-beta of the first residue are 
+not connected by bonds, even though both atoms are in the view. You have either 
+to add the bond manually with
+
+  .. code-block:: python
+  
+    ca_cb=ca.FindBondToAtom(cb)
+    view.AddBond(ca_cb)
+    
+Or as a very convenient shortcut 'view.AddAllInclusiveBonds()' to add all bonds 
+that have both bonding partners in the view.
+
+Don't forget to call update the selection of the graphics object to see what 
+view you have created.
+
+Saving an Entity
+--------------------------------------------------------------------------------
+
+Saving an entity (or a view) is a breeze:
+
+Type
+
+  .. code-block:: python
+  
+     io.SavePDB(fragment, 'full.pdb')
+
+to save the full view. To save only the backbone atoms, we can first select the 
+backbone atoms and then save it:
+
+  .. code-block:: python
+  
+     io.SavePDB(fragment.Select('aname=CA,C,N,O'), 'backbone.pdb')
+
+
+Loading  images and density maps
+--------------------------------------------------------------------------------
+
+Openstructure features a :mod:`~ost.img` module that is dedicated to the 
+manipulation of 
+images/density maps. The images or density maps can either be one-, two- or 
+three-dimensional. The most common formats used in x-ray and electron 
+crystallography and atomic force microscope are supported in addition to several 
+general purpose image formats. See `supported file formats` for details.
+The :mod:`~ost.img` module was originally developed as part of the Image 
+Processing Library & Toolbox IPLT. More documentation and examples can also be 
+found on the `IPLT website <http://www.iplt.org>`_.
+
+To load a density map, type
+
+  .. code-block:: python
+
+     map=io.LoadImage('/path/to/examples/map/1ppt.map')
+
+This will load the fragment density map from the specified file 'fragment.map' 
+and store the result in fragment_map.
+
+Now let's inspect what we just loaded:
+
+  .. code-block:: python
+  
+    print map.GetPixelSampling()
+    
+We can see that the sampling is set to 1.0 Angstroems in all three dimensions.
+
+Manipulating  images and density maps
+--------------------------------------------------------------------------------
+
+The algorithms used for manipulation of an image are found in the 
+:mod:`~ost.img` module. Therefore before using an algorithm we first have to 
+import the :mod:`~ost.img` module.
+
+  .. code-block:: python
+  
+    from ost import img
+
+
+The :mod:`~ost.img` module provides a wide range of algorithm to manipulate 
+image data. Here for the example we use a LowPassFilter to restrict the 
+resolution of the density map.
+
+  .. code-block:: python
+  
+     map_filtered=map.Apply(img.alg.LowPassFilter(3.0))
+
+The filtered map is stored in a new variable called fragment\_map\_filtered.
+
+
+Displaying images and density maps
+--------------------------------------------------------------------------------
+
+Now that we have a filtered map it's time to have a look at it. There are 
+fundamentally two ways to visualize 3-dimensional density maps. One is by 
+drawing isosurfaces. These are conceputally similar to contour lines used in 
+cartography: every point on an isosurface has the same density value. 
+Isosurfaces are easy to create in OpenStructure:
+
+  .. code-block:: python
+  
+     go=gfx.MapIso("filtered", map_filtered,0.5)
+     scene.Add(go)
+
+The other way to visualize a 3-dimensional map is by showing one 2-dimensional 
+density slice at a time, allowing the user to move through the slices. In 
+OpenStructure this is achieved using a DataViewer docs/tut/imgdataviewer.html). 
+A DataViewer showing the filtered map is created using the following command:
+
+  .. code-block:: python
+  
+    gui.CreateDataViewer(map_filtered)
+
+This command displays a panel showing one slice of the density map lying on a 
+particular (x,y) plane in the coordinate reference system.
+The 'z' and 'x' keys can be used to move to slices lying at a lower or higher 
+coordinate along the 'z' axis, allowing the examination of
+the full 3-dimensional volume.
+
+A more detailed explanation of the :mod:`~ost.img` module can be found in the 
+tutorial section for :mod:`~ost.img`.

modules/index.rst

@@ -2,7 +2,13 @@ OpenStructure documentation
 ================================================================================
 
 .. toctree::
-
-  geom/doc/geom
-  conop/doc/conop
-  mol/base/doc/mol
+  :maxdepth: 2
+  
+  intro
+  install.rst
\ No newline at end of file
+  img/base/img
+  img/alg/alg
+  geom/geom
+  conop/conop
+  mol/base/mol
+  seq/base/seq

modules/mol/base/doc/entity.rst

@@ -10,7 +10,7 @@ This document describes the :class:`EntityHandle` and related classes.
 
    Creates a new entity. The created entity is empty, that is, it does not
    contain any atoms, residues, chains, bonds or torsions. To populate the
-   entity, create a new editor.
+   entity, use an :ref:`editor`.
    
    :returns: The newly created :class:`EntityHandle`
    

modules/seq/base/doc/seq.rst

+:mod:`seq` -- Sequences and Alignments
+================================================================================
+
+.. module:: seq
+   :synopsis: Contains classes and functions to deal with sequences and 
+              alignments
+
+The :mod:`seq` module helps you working with sequence data of various kinds. It 
+has classes for :class:`single sequences <SequenceHandle>`, :class:`lists of 
+sequences <SequenceList>` and :class:`alignments <AlignmentHandle>` of two or
+more sequences. 
+
+
+.. _attaching-views:
+
+Attaching Structures to Sequences
+--------------------------------------------------------------------------------
+
+
+Being a structural biology framework, it is not surprising that the sequence 
+classes have been designed to work together with structural data. Each sequence 
+can have an attached :class:`~mol.EntityView` allowing for fast mapping between 
+residues in the entity view and position in the sequence. 
+
+.. _sequence-offset:
+
+Sequence Offset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When using sequences and structures together, often the start of the structure 
+and the beginning of the sequence do not fall together. In the following case, 
+the alignment of sequences B and C only covers a subpart of structure A::
+
+  A acefghiklmnpqrstuvwy
+  B     ghiklm
+  C     123-45
+  
+We would now like to know which residue in protein A is aligned to which residue 
+in sequence C. This is achieved by setting the sequence offset of sequence C to 
+4. In essence, the sequence offset influences all the mapping operations from 
+position in the sequence to residue index and vice versa. By default, the 
+sequence offset is 0.
+
+Loading and Saving Sequences and Alignments
+--------------------------------------------------------------------------------
+
+The :mod:`io` module supports input and output of common sequence formats. 
+Single  sequences can be loaded from disk with :func:`io.LoadSequence`,
+alignments are loaded with :func:`io.LoadAlignment` and lists of sequences are loaded with :func:`io.LoadSequenceList`. In addition to the file based input 
+methods, sequences can also be loaded from a string:
+
+.. code-block:: python
+
+  seq_string='''>sequence
+  abcdefghiklmnop'''
+  s=io.LoadSequenceFromString(seq_string, 'fasta')
+  print s.name, s # will print "sequence abcdefghiklmnop"
+  
+Note that, in that case specifying the format is mandatory.
+
+The SequenceHandle
+--------------------------------------------------------------------------------
+
+.. function:: CreateSequence(name, sequence)
+
+  Create a new :class:`SequenceHandle` with the given name and sequence. 
+  
+  :param name: name of the sequence
+  :type  name: str
+  :param sequence: String of characters representing the sequence. Only   
+       alphanumerical characters and '-' are allowed.
+  :type sequence: str
+  :raises InvalidSequence: When the sequence string contains forbidden
+       characters, that is anything that is not alphanumeric or a hyphen.
+
+.. class:: SequenceHandle
+
+  Represents a sequence. New instances are created with :func:`CreateSequence`.
+  
+  .. method:: GetPos(residue_index)
+  
+    Get position of residue with index in sequence. This is best illustrated in 
+    the following example:
+    
+    .. code-block:: python
+      
+      s=seq.CreateSequence("A", "abc---def")
+      print s.GetPos(1) # prints 1
+      print s.GetPos(3) # prints 6
+    
+    The reverse mapping, that is from position in the sequence to residue index 
+    can be achieved with :meth:`GetResidueIndex`.
+  
+  .. method:: GetResidueIndex(pos)
+     
+    Get residue index of character at given position. This method is the
+    inverse of :meth:`GetPos`. If the sequence contains a gap at that position,
+    an :exc:`Error` is raised.
+    
+    .. code-block:: python
+      
+      s=seq.CreateSequence("A", "abc--def")
+      print s.GetResidueIndex(1) # prints 1
+      print s.GetResidueIndex(6) # prints 4
+      # the following line raises an exception of type
+      # Error with the message "requested position contains 
+      # a gap"
+      print s.GetResidueIndex(3)
+
+  .. method:: GetLastNonGap()
+     
+    Get position of last non-gap character in sequence. In case of an empty
+    sequence, or, a sequence only consisting of hyphens, -1 is returned
+     
+  .. method:: GetFirstNonGap()
+  
+    Get position of first non-gap character in sequence. In case of an empty
+    sequence, or, a sequence only consisting of hyphens, -1 is returned.
+
+  .. method:: AttachView(view)
+              AttachView(view, [chain_name])
+    
+    Attach an :class:`~mol.EntityView` to sequence. The first signature requires
+    that the view contains one chain. If not, an :exc:`IntegrityError` is
+    raised. The second signature will select the chain with the given name. If 
+    no such chain exists, an :exc:`IntegrityError` is raised.
+    
+  .. method:: HasAttachedView()
+  
+    Returns True when the sequence has a view attached, False if not.
+    
+  .. method:: GetAttachedView()
+  
+    Returns the attached :class:`~mol.EntityView`, or an invalid
+    :class:`~mol.EntityView` if no view has been attached. Also available as 
+    the property :attr:`attached_view`.
+    
+  .. method:: GetName()
+  
+    Returns the name of the sequence. Also available as the property
+    :attr:`name`
+  
+  .. method:: SetSequenceOffset()
+  
+    Set the :ref:`sequence offset <sequence-offset>`. By default, the offset is
+    0. Also available as the property :attr:`sequence_offset`.
+    
+  .. method:: GetSequenceOffset()
+    
+    Returns the :ref:`sequence offset <sequence-offset>`. Also available as
+    :attr:`sequence_offset`.
+    
+    
+  .. method:: GetGaplessString()
+     
+    Returns a string version of this sequence with all hyphens removed. Also
+    available as the property :attr:`gapless_string`.
+     
+   
+  .. method:: SetName()
+  
+    Set name of the sequence. Also available as the property :attr:`name`.
+  
+  .. attribute:: gapless_string
+     
+    Shorthand for :meth:`GetGaplessString()`
+     
+  .. attribute:: name
+  
+    Shorthand for :meth:`GetName`/:meth:`SetName`
+  
+  .. attribute:: attached_view
+  
+    Shorthand for :meth:`GetAttachedView`.
+
+  .. attribute:: sequence_offset
+  
+    Shorthand for :meth:`GetSequenceOffset`/:meth:`SetSequenceOffset`
+
+  .. method:: __len__()
+    
+    Returns the length of the sequence (including insertions and deletions)
+    
+  .. method:: __str__()
+
+    Returns the sequence as a string.
+
+
+The SequenceList    
+--------------------------------------------------------------------------------
+
+.. class:: SequenceList
+
+  Represents a list of sequences. The class provides a row-based interface. New
+  instances are created with :func:`CreateSequenceList`.
+
+
+The AlignmentHandle   
+--------------------------------------------------------------------------------
+
+The :class:`AlignmentHandle` represents a list of aligned sequences. In
+constrast to :class:`SequenceList`, an alignment requires all sequences to be of 
+the same length. New instances of alignments are created with 
+:func:`CreateAlignment` and :func:`AlignmentFromSequenceList`.
+
+Typically sequence alignments are used column-based, i.e by looking at an  
+aligned columns in the sequence alignment. To get a row-based (sequence) view
+on the sequence list, use :meth:`GetSequenceList()`. 
+
+All functions that operate on an alignment will again produce a valid alignment. 
+This mean that it is not possible to change the length of one sequence, without  
+adjusting the other sequences, too.
+
+The following example shows how to iterate over the columns and sequences of
+an alignment:
+
+.. code-block:: python
+
+  aln=io.LoadAlignment('aln.fasta')
+  # iterate over the columns
+  for col in aln:
+    print col
+
+  # iterate over the sequences
+  for s in aln.sequences:
+    print s
+
+.. function:: CreateAlignment()
+
+  Creates and returns a new :class:`AlignmentHandle` with no sequences.
+  
+.. function:: AlignmentFromSequenceList(sequences)
+  
+  Create a new alignment from the given list of sequences
+  
+  :param sequences: the list of sequences
+  :type sequences: :class:`ConstSequenceList`
+  
+  :raises: :exc:`InvalidAlignment` if the sequences do not have the same length.
+
+.. class:: AlignmentHandle
+  
+  .. note:: 
+  
+    Several of these methods just forward calls to the sequence. For more 
+    detailed information, have a look at the :class:`SequenceHandle`
+    documentation.
+  
+  .. method:: GetSequence(index)
+  
+    Returns the sequence at the given index, raising an IndexError when trying
+    to access an inexistent sequence.
+    
+  .. method:: GetSequenceList()
+  
+    Returns a list of all sequence of the alignment.
+    
+  .. method:: GetLength()
+  
+    Returns the length of the alignment.
+    
+  .. method:: GetCount()
+  
+    Returns the number of sequences in the alignment.
+  
+  
+  .. method:: ToString(width=80)
+  
+    Returns a formatted string version of the alignment. The sequences are 
+    split into smaller parts to fit into the number columns specified. 
+    
+    .. code-block:: python
+    
+      aln=seq.CreateAlignment()
+      aln.AddSequence(seq.CreateSequence("A", "abcdefghik"))
+      aln.AddSequence(seq.CreateSequence("B", "1234567890"))
+      # The following command will print the output given below
+      print aln.ToString(7)
+      # A abcde
+      # B 12345
+      #
+      # A fghik
+      # B 67890
+
+  .. method:: FindSequence(name)
+  
+    Find sequence with given name. If the alignment contains several sequences
+    with the same name, the first sequence is returned.
+    
+  .. method:: SetSequenceName(seq_index, name)
+  
+    Set the name of the sequence at index `seq_index` to name
+    
+  .. method:: SetSequenceOffset(seq_index, offset)
+  
+    Set the sequence offset of sequence at index `seq_index`
+    
+  .. method:: Copy()
+    
+    Create a deep copy of the alignment
+
+  .. method:: GetPos(seq_index, res_index)
+    
+    Get position of residue with index equal to `res_index` in sequence at index
+    `seq_index`.
+    
+  .. method:: GetResidueIndex(seq_index, pos)
+  
+    Get residue index of residue at position `pos` in sequence at index
+    `seq_index`.
+  
+  .. method:: AttachView(seq_index, view)
+              AttachView(seq_index, view, chain_name)
+    
+    Attach the given view to the sequence at index `seq_index`.
+    
+  .. method:: Cut(start, end)
+  
+    Removes the columns in the half-closed interval `start`, `end` from the
+    alignment.
+    
+    .. code-block:: python
+    
+      aln=seq.CreateAlignment()
+      aln.AddSequence(seq.CreateSequence("A", "abcd---hik"))
+      aln.AddSequence(seq.CreateSequence("B", "1234567890"))
+      aln.Cut(4, 7)
+      
+      print aln.ToString(80)
+      # will print
+      # A abcdhik
+      # B 1234890
+   
+  .. method:: Replace(new_region, start, end)
+  
+    Replace the columns in the half-closed interval `start`, `end` with the
+    columns in `new_region`.
+    
+    :param new_region: The region to be inserted
+    :type new_region: :class:`AlignedRegion` or :class:`AlignmentHandle`
+  
+  
+  .. method:: ShiftRegion(start, end, amount, master=-1)
+  
+    Shift columns in the half-closed interval `start`, `end`. If amount is a
+    positive number, the columns are shifted to the right, if negative, the 
+    columns are shifted to the left.
+    
+    If master is set to -1, all sequences in the region are affected, otherwise 
+    only the sequence at index equal to master is shifted.