adds/cleans docs a bit

docs/source/acls.rst

@@ -1,5 +1,12 @@
-ACLs
-====
+Authentication & Authorization
+==============================
+
+Nefertari currently supports the default Pyramid "auth ticket" cookie method of authentication.
+
+For authorizing access to specific resources, Nefertari uses standard Pyramid access control lists. `See the documentation on Pyramid ACLs to understand how to <http://docs.pylonsproject.org/projects/pyramid/en/1.5-branch/narr/security.html>`_.
+
+ACL API
+-------
 
 .. automodule:: nefertari.acl
     :members:

docs/source/engines.rst → docs/source/database_backends.rst

@@ -1,26 +1,20 @@
-Engines
-=======
+Database Backends
+=================
 
-Engines in the context of Nefertari are wrappers/abstractions around existing backend ORMs/interfaces/modules etc. There are currently two engines available:
+Nefertari implements database engines on top of two different ORMs: `SQLAlchemy <http://www.sqlalchemy.org>`_ and `MongoEngine <http://mongoengine.org/>`_. As such, Nefertari can be used with exising models implemented using either mapper library.
 
-* 'sqla' engine is based at SQLAlchemy.
-* 'mongodb' engine is based at MongoEngine
-
-These engines are meant to provide almost exact API and be easily switchable without side-effects.
-
-
-Engines API:
+These two engines wrap the underlying APIs of each ORM and provide a standardized syntax for using either one, making it easy to switch between them with minimal changes.
 
+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/>`_
 
 
-Common API
-----------
+Wrapper API
+-----------
 
-.. if this changes, it must be updated in docs for nefertari{-sqla|mongodb}
-.. TODO: figure out how to include common elements in templates
+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>`_.
 
 **BaseMixin**
     Mixin with a most of the API of *BaseDocument*. *BaseDocument* subclasses from this mixin.

docs/source/elasticsearch.rst

@@ -6,7 +6,21 @@ Nefertari uses `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_
 Making requests
 ---------------
 
-For models which subclass ESBaseDocument in your project, you may pass various  parameters in the URL to use the search API. See the list of parameters on the `nefertari-example project's readme <https://github.com/brandicted/nefertari-example>`_.
+For models which subclass ESBaseDocument in your project, you may pass various parameters in the URL to use the search API.
+
+===========================			===========
+url parameter						description
+===========================			===========
+_m=<method>							to force an http method using GET, e.g. _m=POST
+q=<keywords>						to filter an ElasticSearch collection using 'keyword ((AND
+_fields=<field_list>				to display only specific fields, use - before field names to exclude those fields, e.g. _fields=-descripton
+_search_fields=<field_list>			use with ?q=<keywords> to restrict search to specific fields
+_limit=<n>							to limit the returned collection to n results (default is 20, max limit is 100 for unauthenticated users)
+_sort=<field>						to sort collection by <field>
+_start=<n>							to start collection from the <n>th resource
+_page=<n>							to start collection at page <n> (n * _limit)
+===========================			===========
+
 
 
 Indexation script

docs/source/getting_started.rst

@@ -151,7 +151,7 @@ Each view must define the following properties:
 
 Optional properties:
 
-    * *_json_encoder*: encoder to encode objects to JSON. Engine-specific encoders are available at ``nefertari.engine.JSONEncoder``.
+    * *_json_encoder*: encoder to encode objects to JSON. Database-specific encoders are available at ``nefertari.engine.JSONEncoder``.
 
 Your views should sit in a package and each module of that package should contain views for a particular root level route. In our example, the ``users`` route view must be at ``views.users.UsersView``.
 

docs/source/index.rst

@@ -3,25 +3,19 @@ Nefertari, queen of APIs
 
 Github: `<http://github.com/brandicted/nefertari>`_
 
-She is a REST API framework for Pyramid that uses Elasticsearch and optionally other backends.
-
-See `nefertari-sqla <http://nefertari-sqla.readthedocs.org/en/latest/>`_ for SQLalchemy support and `nefertari-mongodb <http://nefertari-mongodb.readthedocs.org/en/latest/>`_ for MongoDB.
+Nefertari is a REST API framework for Pyramid that uses Elasticsearch for reads and either MongoDB or Postgres for writes.
 
 Nefertari currently powers `Brandicted <http://brandicted.com/>`_ and `Cerri <http://www.cerri.com/>`_. She is fully production ready and actively maintained.
 
-.. image:: nefertari.jpg
-
-Image credit: Wikipedia
-
-
 Contents
 ========
 
 .. toctree::
    :maxdepth: 2
 
+   overview
    getting_started
-   engines
+   database_backends
    acls
    elasticsearch
    example_project
@@ -33,3 +27,7 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`search`
+
+.. image:: nefertari.jpg
+
+Image credit: Wikipedia

docs/source/overview.rst

@@ -0,0 +1,32 @@
+Overview
+========
+
+Nefertari is a tool for making REST APIs using the Pyramid web framework.
+
+
+Rationale
+---------
+
+There are many other libaries that make writing REST APIs easy. Nefertari did not begin as a tool. It was extracted from the API powering `Brandicted <https://brandicted.com/>`_ after almost two years of development.
+
+We wanted to build powerful REST APIs that are relatively opinionated but still flexible (in order to make easy things easy and hard things possible). We happened to need to use Postgres on a side project, but Brandicted's API only supported MongoDB.
+
+Before extracting Nefertari and turning it into an open soruce project, we shopped around the Python ecosystem and tested every REST API library/framework to see what would allow us to be as lazy as possible and also allow our APIs to grow bigger over time.
+
+The most convenient option was the beautiful `flask-restless <https://flask-restless.readthedocs.org/en/latest/>`_ by Jeffrey Finkelstein. It depends on Postgres and does a really good job being super easy to use. We had some subjective fears about using Flask because of globals and the fact that our closest community members happen to be Pyramid folks.
+
+We were also inspired by `pyramid-royal <https://pyramid-royal.readthedocs.org/en/latest/>`_ from our fellow Montreal Python colleague Hadrien David. He showed how traversal is a-ok for matching routes in a tree of resources, which is what REST should be anyway.
+
+However, we had become quite used to the power of using Elasticsearch over the years and wanted to retain the option of using it as a first class citizen to power most GET views. Therefore we decided to add Postgres support to our platform, and thus was born Nefertari.
+
+
+Vision
+------
+
+To us, "REST API" means something like "HTTP verbs mapped to CRUD operations on resources decribed as JSON". We are not trying to do full-on `HATEOAS <https://en.wikipedia.org/wiki/HATEOAS>`_ to satisfy any academic ideal of the REST style. There are quite a few development tasks that can be abstracted away by using our simple definition.
+
+By making assumptions about sane defaults, we can eliminate the need for boilerplate to do things like serialization, URL mapping, validation, authentication/authorization, versioning, testing, database queries in views, etc. The only things that should absolutely need to be defined are the resources themselves, and they should just know how to act in a RESTful way by default. They should be configurable to a degree and extendable in extreme cases. Contrast this idea with something like the `Django Rest Framework <http://www.django-rest-framework.org/#api-guide>`_ [#]_  :)
+
+Nefertari is the meat and potatoes of our development stack. Her partner project, Ramses, is the seasoning/sugar/cherry on top! Ramses allows whole production-ready Nefertari apps to be generated at runtime from a simple YAML file specifying the endpoints desired. `Check it out. <https://ramses.readthedocs.org/en/latest/>`_
+
+.. [#] For the record, DRF is pretty badass and we have great respect for its breadth and the hard work of its community.