adding more documentation on making request on ES-backed collections

docs/source/database_backends.rst

@@ -10,11 +10,13 @@ Each Nefertari engine is developed in its own repository:
 * `SQLA Engine <http://nefertari-sqla.readthedocs.org/en/latest/>`_
 * `MongoDB Engine <http://nefertari-mongodb.readthedocs.org/en/latest/>`_
 
+Nefertari can use `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_ to read/GET any given resource. You can read more about **ESBaseDocument** in the `Wrapper API <database_backends.html#wrapper-api>`_ section below.
+
 
 Wrapper API
 -----------
 
-Both of the database engines used by Nefertari implement the exact same "common API" for developers to use within a Nefertari project. Use the following base classes in your project to leverage the powers of Nefertari. To see them in action, check out the `example project <https://github.com/brandicted/nefertari-example>`_.
+Both of the database engines used by Nefertari implement a similar "Wrapper API" for developers to use within a Nefertari project. Use the following base classes in your project to leverage the powers of Nefertari. To see them in action, check out the `example project <https://github.com/brandicted/nefertari-example>`_.
 
 **BaseMixin**
     Mixin with a most of the API of *BaseDocument*. *BaseDocument* subclasses from this mixin.

docs/source/development_tools.rst

@@ -0,0 +1,24 @@
+Development Tools
+-----------------
+
+"nefertari.index" console script can be used to manually index models from your database engine to Elasticsearch.
+
+You can run it like so::
+
+    $ nefertari.index --help
+
+The options available are:
+
+**config**: specify ini file to use (required). E.g.::
+
+    $ nefertari.index --config local.ini
+
+**models**: list of dotted paths of models to index. Models must be subclasses of ESBaseDocument.  E.g.::
+
+    $ nefertari.index --config local.ini --models example_api.model.Story
+
+**params**: URL-encoded parameters for each module.
+**quiet**: "quiet mode" (surpress output)
+**index**: Specify name of index. E.g. the slug at the end of http://localhost:9200/example_api
+**chunk**: Index chunk size.
+**force**: Force re-indexation of all documents in database engine (defaults to False).

docs/source/index.rst

@@ -17,7 +17,8 @@ Contents
    getting_started
    database_backends
    acls
-   elasticsearch
+   making_requests
+   development_tools
    example_project
    changelog
 

docs/source/making_requests.rst

@@ -0,0 +1,31 @@
+Making requests
+===============
+
+Query syntax
+------------
+
+===============================             ===========
+url parameter                               description
+===============================             ===========
+``_m=<method>``                             to tunnel any http method using GET, e.g. _m=POST
+``_limit=<n>``                              to limit the returned collection to <n> results (default: 20, max limit: 100 for unauthenticated users)
+``_sort=<field_name>``                      to sort collection by <field_name>
+``_start=<n>``                              to start collection from the <n>th resource
+``_page=<n>``                               to start collection at page <n> (n * _limit)
+``_fields=<field_list>``                    to display only specific fields, use ``-`` before field names to exclude those fields, e.g. ``_fields=-descripton``
+===============================             ===========
+
+Query syntax for ElasticSearch
+------------------------------
+
+Additional parameters are available when using an ElasticSearch-enabled collection (see **ESBaseDocument** in the `Wrapper API <database_backends.html#wrapper-api>`_ section of this documentation).
+
+===============================             ===========
+url parameter                               description
+===============================             ===========
+``<field_name>=<keywords>``                 to filter a collection using full-text search on <field_name>, ElasticSearch operators [#]_ can be used, e.g. ``?title=foo AND bar``
+``q=<keywords>``                            to filter a collection using full-text search on all fields
+``_search_fields=<field_list>``             use with ``?q=<keywords>`` to restrict search to specific fields
+===============================             ===========
+
+.. [#] The full syntax of ElasticSearch querying is beyond the scope of this documentation. You can read more on the `ElasticSearch Query String Query <http://www.elastic.co/guide/en/elasticsearch/reference/1.x/query-dsl-query-string-query.html>`_ page and more specifically on `Ranges <http://www.elastic.co/guide/en/elasticsearch/reference/1.x/query-dsl-query-string-query.html#_ranges_2>`_ to do things like: ``?date=[2014-01-01 TO *]``