From 3bea01e281185ef9c55af0e82504bd9942674a64 Mon Sep 17 00:00:00 2001
From: Tal Einat <taleinat@gmail.com>
Date: Wed, 12 Mar 2014 15:59:37 +0200
Subject: [PATCH] additional documentation improvements (mostly examples)

---
 README.rst              |  9 ++++++++-
 docs/usage.rst          | 32 +++++++++++++++++++++++++-------
 fuzzysearch/__init__.py |  4 ++--
 3 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/README.rst b/README.rst
index 3e69a26..fd27a17 100644
--- a/README.rst
+++ b/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 = '''\
diff --git a/docs/usage.rst b/docs/usage.rst
index 8e229b2..f5080b5 100644
--- a/docs/usage.rst
+++ b/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)]
diff --git a/fuzzysearch/__init__.py b/fuzzysearch/__init__.py
index ac12e5c..d8ec530 100644
--- a/fuzzysearch/__init__.py
+++ b/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.