Updated documentation.

README.rst

@@ -24,10 +24,45 @@ Back translation
 
 ----
 
-This library provides functions for back translation from amino acids to
-nucleotides.
+This library provides functions for back translation of amino acid changes to
+nucleotide changes.
+
+**Features:**
+
+- Support for all known codon tables.
+- Back translation of amino acid changes using codon reference information.
+- Back translation of amino acid changes using amino acid reference
+  information.
+- Function to determine all amino acid substitutions of which the back
+  translation can be improved by adding codon information.
 
 Please see ReadTheDocs_ for the latest documentation.
 
 
+Quick start
+-----------
+
+The ``BackTranslate`` class provides functionality for back translation.
+
+.. code:: python
+
+    >>> from mutalyzer_backtranslate import BackTranslate
+    >>> bt = BackTranslate()
+
+An amino acid change from a Leucine to a Phenylalanine can be explained by five
+substitutions.
+
+.. code:: python
+    >>> bt.without_dna('L', 'F')
+    {2: {('A', 'T'), ('A', 'C'), ('G', 'C'), ('G', 'T')}, 0: {('C', 'T')}}
+
+If codon information is present, the same substitution can only be explained by
+one substitution.
+
+.. code:: python
+
+    >>> bt.with_dna('CTT', 'F')
+    {0: {('C', 'T')}}
+
+
 .. _ReadTheDocs: https://mutalyzer-backtranslate.readthedocs.io

docs/conf.py

-import os
-import subprocess
-import sys
+from subprocess import call
 
-subprocess.call('pip install ..', shell=True)
+call('pip install ..', shell=True)
 
 from mutalyzer_backtranslate import _get_metadata
 

docs/introduction.rst

 Introduction
 ============
+
+Back translation or Reverse translation is the conversion of a protein sequence
+into a nuclear sequence. In general, there are multiple nuclear sequences that
+can be translated into the same protein sequence, so the reverse of this
+operation usually results in a large number of candidate nuclear sequences.
+
+A related problem is the back translation of an amino acid *change* to a
+nuclear *change*. In this case, we know a reference amino acid and an observed
+amino acid and we are interested in the nuclear variant that gave rise to this
+change. Since there are infinitely many ways of making such a transformation,
+we restrict ourselves to substitutions of one nucleotide that may explain the
+observed amino acid change.
+
+For example, we might be interested in which nucleotide substitutions will
+transform a Tryptophan into a stop codon. It turns out that there are two
+possible one nucleotide substitutions that have this effect; replace either
+``G`` with an ``A``.
+
+This form of back translation can be done by making use of reference
+information. This information can be provided in the form of a reference amino
+acid, or a reference codon. In general, using a reference codon will yield
+fewer possibilities when compared to using a reference amino acid.
+
+For example, there are five one nucleotide substitutions that can transform a
+Leucine to a Phenylalanine. If we happen to know that the reference codon was
+``CTT`` though, then there is only one substitution that can explain this
+transformation.
+
+This library provides functionality to back translate amino acid changes using
+either a reference amino acid or a reference codon. Furthermore, it provides a
+function that, given a codon table, will list all amino acid substitutions of
+which the back translation can be improved by adding codon information.

docs/library.rst

 Library
 =======
 
-The library provides functions for back translation from amino acids to
-nucleotides.
+This library provides functions for back translation from amino acid changes to
+nucleotide changes.
 
 .. code:: python