Update docs and readme/index.

README.md

@@ -6,15 +6,21 @@ Lightweight Python utilities for working with [Redis](http://redis.io).
 
 The purpose of [walrus](https://github.com/coleifer/walrus) is to make working with Redis in Python a little easier by wrapping rich objects in Pythonic containers. walrus consists of:
 
-* Wrappers for the Redis object types:
+* Pythonic container classes for the Redis data-types:
     * [Hash](https://walrus.readthedocs.io/en/latest/containers.html#hashes)
     * [List](https://walrus.readthedocs.io/en/latest/containers.html#lists)
     * [Set](https://walrus.readthedocs.io/en/latest/containers.html#sets)
     * [Sorted Set](https://walrus.readthedocs.io/en/latest/containers.html#sorted-sets-zset)
     * [HyperLogLog](https://walrus.readthedocs.io/en/latest/containers.html#hyperloglog)
     * [Array](https://walrus.readthedocs.io/en/latest/containers.html#arrays) (custom type)
-* A simple [Cache](https://walrus.readthedocs.io/en/latest/cache.html) implementation that exposes several decorators for caching function and method calls.
-* Lightweight data [Model](https://walrus.readthedocs.io/en/latest/models.html) objects that support persisting structured information and performing complex queries using secondary indexes.
+* [Autocomplete](https://walrus.readthedocs.io/en/latest/autocomplete.html)
+* [Cache](https://walrus.readthedocs.io/en/latest/cache.html) implementation that exposes several decorators for caching function and method calls.
+* [Full-text search](https://walrus.readthedocs.io/en/latest/full-text-search.html) supporting set operations.
+* [Graph store](https://walrus.readthedocs.io/en/latest/graph.html)
+* [Rate-limiting](https://walrus.readthedocs.io/en/latest/rate-limit.html)
+* [Locking](https://walrus.readthedocs.io/en/latest/api.html#walrus.Lock)
+* Active-record style [Models](https://walrus.readthedocs.io/en/latest/models.html) that support persisting structured information and performing complex queries using secondary indexes.
+* More? [More!](https://walrus.readthedocs.io)
 
 ### Models
 

docs/full-text-search.rst

@@ -0,0 +1,85 @@
+.. _full-text-search:
+
+Full-text Search
+================
+
+Walrus comes with a standalone full-text search index that supports:
+
+* Storing documents along with arbitrary metadata.
+* Complex search using boolean/set operations and parentheses.
+* Stop-word removal.
+* Porter-stemming.
+* Optional double-metaphone for phonetic search.
+
+To create a full-text index, use:
+
+* :py:meth:`Database.Index`
+* :py:class:`Index`
+
+Example:
+
+.. code-block:: python
+
+    from walrus import Database
+
+    db = Database()
+    search_index = db.Index('app-search')
+
+    # Phonetic search.
+    phonetic_index = db.Index('phonetic-search', metaphone=True)
+
+Storing data
+------------
+
+Use the :py:meth:`Index.add` method to add documents to the search index:
+
+.. code-block:: python
+
+    # Specify the document's unique ID and the content to be indexed.
+    search_index.add('doc-1', 'this is the content of document 1')
+
+    # Besides the document ID and content, we can also store metadata, which is
+    # not searchable, but is returned along with the document content when a
+    # search is performed.
+    search_index.add('doc-2', 'another document', title='Another', status='1')
+
+To update a document, use either the :py:meth:`Index.update` or
+:py:meth:`Index.replace` methods. The former will update existing metadata
+while the latter clears any pre-existing metadata before saving.
+
+.. code-block:: python
+
+    # Update doc-1's content and metadata.
+    search_index.update('doc-1', 'this is the new content', title='Doc 1')
+
+    # Overwrite doc-2...the "status" metadata value set earlier will be lost.
+    search_index.replace('doc-2', 'another document', title='Another doc')
+
+To remove a document use :py:meth:`Index.remove`:
+
+.. code-block:: python
+
+    search_index.remove('doc-1')  # Removed from index and removed metadata.
+
+Searching
+---------
+
+Use the :py:meth:`Index.search` method to perform searches. The search query
+can include set operations (e.g. *AND*, *OR*) and use parentheses to indicate
+operation precedence.
+
+.. code-block:: python
+
+    for document in search_index.search('python AND flask'):
+        # Print the "title" that was stored as metadata. The "content" field
+        # contains the original content of the document as it was indexed.
+        print(document['title'], document['content'])
+
+Phonetic search, using ``metaphone``, is tolerant of typos:
+
+.. code-block:: python
+
+    for document in phonetic_index.search('flasck AND pythonn'):
+        print(document['title'], document['content'])
+
+For more information, see the :py:class:`Index` API documentation.

docs/index.rst

@@ -15,6 +15,7 @@ Python utilities for working with `Redis <http://redis.io>`_:
 * container classes
 * autocomplete
 * cache
+* full-text search
 * graph store
 * rate limiting
 * active-record models (secondary indexes, full-text search)
@@ -39,6 +40,7 @@ Contents:
    containers
    autocomplete
    cache
+   full-text-search
    graph
    rate-limit
    models