Add small usage example to Alignment and fix some documentation issues

docs/_static/json/switcher.json

@@ -5,7 +5,7 @@
         "url": "https://pyfamsa.readthedocs.io/en/v0.3.3/"
     },
     {
-        "name": "v0.3 (latest)",
+        "name": "v0.3",
         "version": "0.3.2",
         "url": "https://pyfamsa.readthedocs.io/en/v0.3.2/"
     },

docs/api/alignment.rst

@@ -5,4 +5,5 @@ Alignment
 
 .. autoclass:: pyfamsa.Alignment
    :inherited-members:
+   :special-members: __init__, __len__, __getitem__
    :members:

docs/api/gapped_sequence.rst

@@ -0,0 +1,9 @@
+Gapped Sequence
+===============
+
+.. currentmodule:: pyfamsa
+
+.. autoclass:: pyfamsa.GappedSequence
+  :inherited-members:
+  :special-members: __init__
+  :members:

docs/api/index.rst

@@ -3,6 +3,17 @@ API Reference
 
 .. currentmodule:: pyfamsa
 
+.. toctree::
+   :caption: API Reference
+   :hidden:
+
+   Aligner <aligner>
+   Sequence <sequence>
+   Gapped Sequence <sequence>
+   Alignment <alignment>
+   Guide Tree <guide_tree>
+
+
 Aligner
 -------
 
@@ -11,12 +22,6 @@ Aligner
 
     Aligner
 
-.. toctree::
-   :caption: Aligner
-   :hidden:
-
-   aligner <aligner>
-
 
 Sequence
 --------
@@ -27,12 +32,6 @@ Sequence
     Sequence
     GappedSequence
 
-.. toctree::
-   :caption: Sequence
-   :hidden:
-
-   sequence <sequence>
-
 
 Alignment
 ---------
@@ -42,12 +41,6 @@ Alignment
 
     Alignment
 
-.. toctree::
-   :caption: Alignment
-   :hidden:
-
-   alignment <alignment>
-
 
 GuideTree
 ---------
@@ -56,9 +49,3 @@ GuideTree
     :nosignatures:
 
     GuideTree
-
-.. toctree::
-   :caption: GuideTree
-   :hidden:
-
-   guide_tree <guide_tree>

docs/api/sequence.rst

@@ -5,8 +5,5 @@ Sequence
 
 .. autoclass:: pyfamsa.Sequence
    :inherited-members:
+   :special-members: __init__
    :members:
-
-.. autoclass:: pyfamsa.GappedSequence
-  :inherited-members:
-  :members:

docs/index.rst

@@ -102,16 +102,6 @@ has the following advantages:
       Access all the features of the original CLI through the :doc:`Python API <api/index>`.
 
 
-- **single dependency**: ``pyfamsa`` is distributed as a Python package, so you
-  can add it as a dependency to your project, and stop worrying about the
-  FAMSA binary being present on the end-user machine.
-- **no intermediate files**: Everything happens in memory, in a Python object
-  you control, so you don't have to invoke the FAMSA CLI using a
-  sub-process and temporary files.
-- **friendly interface**: The different guide tree build methods and
-  heuristics can be selected from the Python code with a simple keyword
-  argument when configuring a new `Aligner`.
-
 
 Setup
 -----

pyfamsa/_famsa.pyx

@@ -340,6 +340,23 @@ cdef class GappedSequence:
 
 cdef class Alignment:
     """An alignment, stored as a list of `GappedSequence` objects.
+
+    An alignment can be created from an iterable of `GappedSequence` that
+    are all the same gapped size::
+
+        >>> s1 = GappedSequence(b"seq1", b"MA-WMRLLPL")
+        >>> s2 = GappedSequence(b"seq2", b"MALWTR-RPL")
+        >>> alignment = Alignment([s1, s2])
+
+    The individual rows of the alignment can be accessed using the usual
+    indexing operation, and the alignment can be sliced to select only
+    certain rows::
+
+        >>> alignment[0].id
+        b'seq1'
+        >>> len(alignment[:1])
+        1
+
     """
 
     # --- Magic methods ------------------------------------------------------
@@ -386,25 +403,31 @@ cdef class Alignment:
         return self._msa.size()
 
     def __getitem__(self, object index):
-        cdef GappedSequence gapped
-        cdef ssize_t        index_
-        cdef size_t         length = self._msa.size()
+        cdef GappedSequence   gapped
+        cdef CGappedSequence* gseq
+        cdef ssize_t          index_
+        cdef Alignment        ali
+        cdef size_t           length = self._msa.size()
 
         if isinstance(index, slice):
             indices = range(*index.indices(length))
-            return self.__class__(self[i] for i in indices)
-
-        index_ = index
-        if index_ < 0:
-            index_ += self._msa.size()
-        if index_ < 0 or index_ >= <ssize_t> self._msa.size():
-            raise IndexError(index)
-
-        gapped = GappedSequence.__new__(GappedSequence)
-        gapped.alignment = self
-        gapped._owned = True
-        gapped._gseq = self._msa[index_]
-        return gapped
+            ali = Alignment.__new__(Alignment)
+            for i in indices:
+                gseq = new CGappedSequence(self._msa[i][0])
+                gseq.original_no = gseq.sequence_no = ali._msa.size()
+                ali._msa.push_back(gseq)
+            return ali
+        else:
+            index_ = index
+            if index_ < 0:
+                index_ += self._msa.size()
+            if index_ < 0 or index_ >= <ssize_t> self._msa.size():
+                raise IndexError(index)
+            gapped = GappedSequence.__new__(GappedSequence)
+            gapped.alignment = self
+            gapped._owned = True
+            gapped._gseq = self._msa[index_]
+            return gapped
 
     # --- Methods ------------------------------------------------------------
 
@@ -452,7 +475,9 @@ cdef class Aligner:
         object refine=None,
         object scoring_matrix=None,
     ):
-        """Create a new aligner with the given configuration.
+        """__init__(self, *, threads=0, guide_tree="sl", tree_heuristic=None, medoid_threshold=0, n_refinements=100, keep_duplicates=False, refine=None, scoring_matrix=None)\n--\n
+        
+        Create a new aligner with the given configuration.
 
         Keyword Arguments:
             threads (`int`): The number of threads to use for parallel