additional documentation improvements (mostly examples)

README.rst

@@ -4,7 +4,7 @@ fuzzysearch
 
 .. image:: https://badge.fury.io/py/fuzzysearch.png
     :target: http://badge.fury.io/py/fuzzysearch
-    
+
 .. image:: https://travis-ci.org/taleinat/fuzzysearch.png?branch=master
         :target: https://travis-ci.org/taleinat/fuzzysearch
 
@@ -24,6 +24,10 @@ Features
 
 Simple Example
 --------------
+You can usually just use the `find_near_matches()` utility function, which
+chooses a suitable fuzzy search implementation according to the given
+parameters:
+
 .. code:: python
 
     >>> from fuzzysearch import find_near_matches
@@ -32,6 +36,9 @@ Simple Example
 
 Advanced Example
 ----------------
+If needed you can choose a specific search implementation, such as
+`find_near_matches_with_ngrams()`:
+
 .. code:: python
 
     >>> sequence = '''\

docs/usage.rst

@@ -2,15 +2,33 @@
 Usage
 ========
 
-To use fuzzysearch in a project:
-
-.. code:: python
-
-	import fuzzysearch
-
-A simple example:
+Simple Example
+--------------
+You can usually just use the `find_near_matches()` utility function, which
+chooses a suitable fuzzy search implementation according to the given
+parameters:
 
 .. code:: python
 
+    >>> from fuzzysearch import find_near_matches
     >>> find_near_matches('PATTERN', 'aaaPATERNaaa', max_l_dist=1)
     [Match(start=3, end=9, dist=1)]
+
+Advanced Example
+----------------
+If needed you can choose a specific search implementation, such as
+`find_near_matches_with_ngrams()`:
+
+.. code:: python
+
+    >>> sequence = '''\
+    GACTAGCACTGTAGGGATAACAATTTCACACAGGTGGACAATTACATTGAAAATCACAGATTGGTCACACACACA
+    TTGGACATACATAGAAACACACACACATACATTAGATACGAACATAGAAACACACATTAGACGCGTACATAGACA
+    CAAACACATTGACAGGCAGTTCAGATGATGACGCCCGACTGATACTCGCGTAGTCGTGGGAGGCAAGGCACACAG
+    GGGATAGG'''
+    >>> subsequence = 'TGCACTGTAGGGATAACAAT' #distance 1
+    >>> max_distance = 2
+
+    >>> from fuzzysearch import find_near_matches_with_ngrams
+    >>> find_near_matches_with_ngrams(subsequence, sequence, max_distance)
+    [Match(start=3, end=24, dist=1)]

fuzzysearch/__init__.py

@@ -31,8 +31,8 @@ from fuzzysearch.custom_search import find_near_matches_customized_levenshtein
 def find_near_matches(subsequence, sequence, max_l_dist):
     """Find near-matches of the subsequence in the sequence.
 
-    This chooses an appropriate fuzzy search implementation according to the
-    given maximum Levenshtein distance.
+    This chooses a suitable fuzzy search implementation according to the given
+    parameters.
 
     Returns a list of fuzzysearch.Match objects describing the matching parts
     of the sequence.