revised documentation in preparation of 0.2.2

ramses-tech · May 15, 2015 · 2a7f4ad · 2a7f4ad
1 parent 8e7a908
commit 2a7f4ad
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 49 deletions.
diff --git a/docs/source/database_backends.rst b/docs/source/database_backends.rst
@@ -1,6 +1,9 @@
 Database Backends
 =================
 
+Introduction
+------------
+
 Nefertari implements database engines on top of two different ORMs: `SQLAlchemy <http://www.sqlalchemy.org>`_ and `MongoEngine <http://mongoengine.org/>`_. 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 maintained in its own repository:
@@ -11,7 +14,7 @@ Each Nefertari engine is maintained in its own repository:
 Nefertari can either use `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_ or the database engine itself to read (GET) any given resource. You can read more about **ESBaseDocument** in the `Wrapper API <database_backends.html#wrapper-api>`_ section below.
 
 Field abstractions
--------------------
+------------------
 
 * BigIntegerField
 * BooleanField

diff --git a/docs/source/example_project.rst b/docs/source/example_project.rst
@@ -1,4 +1,4 @@
 Example Project
 ===============
 
-For an example of how to use Nefertari see the `Example Project <https://github.com/brandicted/nefertari-example>`_.
+For a more complete example of a Pyramid project using Nefertari, you can take a look at the `Example Project <https://github.com/brandicted/nefertari-example>`_.
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,47 +1,51 @@
 Getting started
 ===============
 
-**1. Create a Pyramid "starter" project** in a virtualenv directory (see the `pyramid documentation <http://docs.pylonsproject.org/docs/pyramid/en/latest/narr/project.html>`_)::
+**1. Create a Pyramid "starter" project** in a virtualenv directory (see the `pyramid documentation <http://docs.pylonsproject.org/docs/pyramid/en/latest/narr/project.html>`_)
 
+.. code-block:: shell
+
+    $ mkvirtualenv MyProject
+    $ pip install nefertari
     $ pcreate -s starter MyProject
     $ cd MyProject
     $ pip install -e .
 
-Install nefertari and the database backend you want to use, e.g. sqla or mongodb::
+Install the database backend of your choice, e.g. sqla or mongodb
+
+.. code-block:: shell
 
-    $ pip install nefertari
     $ pip install nefertari-<engine>
 
-**2. Add a few settings** to your .ini file under the ``[app:main]`` section
+
+**2. Add a few settings** to development.ini, inside the ``[app:main]`` section
 
 .. code-block:: ini
 
     # Elasticsearh settings
     elasticsearch.hosts = localhost:9200
     elasticsearch.sniff = false
-    elasticsearch.index_name = MyProject
+    elasticsearch.index_name = myproject
     elasticsearch.index.disable = false
 
-    # enable/disable authentication
+    # disable authentication
     auth = false
 
-    # Max number of objects returned to unauthenticated users (if auth = true)
-    public_max_limit = 100
-
     # Set '<nefertari_engine>' (e.g. nefertari_sqla or nefertari_mongodb)
     nefertari.engine = <nefertari_engine>
 
 .. code-block:: ini
 
     # For sqla:
-    sqlalchemy.url = postgresql://localhost:5432/MyProject
+    sqlalchemy.url = postgresql://localhost:5432/myproject
 
 .. code-block:: ini
 
     # For mongo:
     mongodb.host = localhost
     mongodb.port = 27017
-    mongodb.db = MyProject
+    mongodb.db = myproject
+
 
 **3. Replace the file** `myproject/__init__.py`
 
@@ -65,10 +69,8 @@ Install nefertari and the database backend you want to use, e.g. sqla or mongodb
         from .models import Item
         root.add(
             'myitem', 'myitems',
-            id_name='myitem_' + Item.pk_field(),
             view='myproject.views.ItemsView')
 
-
         # Use the engine helper to bootstrap the db
         from nefertari.engine import setup_database
         setup_database(config)
@@ -77,12 +79,12 @@ Install nefertari and the database backend you want to use, e.g. sqla or mongodb
         # Launch the server in the way that works for you
         return config.make_wsgi_app()
 
+
 **4. Replace the file** `myproject/views.py`
 
 .. code-block:: python
 
     from nefertari.view import BaseView
-    from nefertari.engine import JSONEncoder
     from nefertari.elasticsearch import ES
     from nefertari.json_httpexceptions import (
         JHTTPCreated, JHTTPOk)
@@ -94,40 +96,31 @@ Install nefertari and the database backend you want to use, e.g. sqla or mongodb
         _model_class = Item
 
         def index(self):
+            self._query_params.process_int_param('_limit', 20)
             return ES('Item').get_collection(**self._query_params)
 
         def show(self, **kwargs):
-            return self.context
+            return ES('Item').get_resource(**kwargs)
 
         def create(self):
             story = Item(**self._json_params)
-            story.arbitrary_object = ArbitraryObject()
             story.save()
             pk_field = Item.pk_field()
             return JHTTPCreated(
-                location=self.request._route_url(
-                    'items', getattr(story, pk_field)),
                 resource=story.to_dict(),
                 request=self.request,
             )
 
         def update(self, **kwargs):
             pk_field = Item.pk_field()
-            kwargs = self.resolve_kwargs(kwargs)
             story = Item.get_resource(**kwargs).update(self._json_params)
-
-            return JHTTPOk(
-                location=self.request._route_url(
-                'items',
-                getattr(story, pk_field))
-            )
+            return JHTTPOk()
 
         def delete(self, **kwargs):
-            kwargs = self.resolve_kwargs(kwargs)
             Item._delete(**kwargs)
-
             return JHTTPOk()
 
+
 **5. Create the file** `myproject/models.py`
 
 .. code-block:: python
@@ -147,21 +140,8 @@ Install nefertari and the database backend you want to use, e.g. sqla or mongodb
         description = eng.TextField()
 
 
+**5. Run your app**
 
-Notes:
-
-When using SQLA, each view must define the following properties:
-    * *_model_class*: class of the model that is being served by this view.
-
-Optional properties:
-    * *_json_encoder*: encoder to encode objects to JSON. Database-specific encoders are available at ``nefertari.engine.JSONEncoder``.
-
-Your views should reside 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``. Or you can explicitly provide view name, or view class as ``view`` keyword argument to ``resource.add()`` in your project's ``main`` function.
-
-Note that in case of a singular resource (i.e. Likes), there is no "index" view and "show" returns only the one item.
-Also, note that "delete", "update" and other actions that would normally require an id, do not in Nefertari, because there is only one object being referenced.
-
-4. Define your models using abstractions imported from 'nefertari.engine'. For more information on abstractions, see :doc:`engines/index` section.
-
-5. Run your app with ``pserve settings_file.ini`` and request the routes you defined.
+.. code-block:: shell
 
+    $ pserve development.ini
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -13,13 +13,14 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   overview
    getting_started
+   views
    database_backends
    auth
    making_requests
    development_tools
    example_project
+   why
    changelog
 
 

diff --git a/docs/source/views.rst b/docs/source/views.rst
@@ -0,0 +1,24 @@
+Configuring views
+=================
+
+Introduction
+------------
+
+It is recommended that your views reside in a package. In this case, each module of that package would contain all views of any given root-level route. Alternatively, ou can explicitly provide a view name, or a view class as ``view`` keyword argument to ``resource.add()`` in your project's ``main`` function. In the case of a singular resource, there is no need to define ``index`` and ``show`` returns only one item.
+
+* *index*: called upon ``GET`` request to a collection, e.g. ``/collection``
+* *show*: called upon ``GET`` request to a collection-item, e.g. ``/collection/<id>``
+* *create*: called upon ``POST`` request to a collection
+* *update*: called upon ``PATCH`` request to a collection-item
+* *delete*: called upon ``DELETE`` request to a collection-item
+* *update_many*: called upon ``PATCH`` request to a collection or filtered collection, e.g. ``/collection?_exists_=<field>``
+* *delete_many*: called upon ``DELETE`` request to a collection or filtered collection
+
+Notes
+-----
+
+When using SQLA, each view must define the following properties:
+    * *_model_class*: class of the model that is being served by this view.
+
+Optional properties:
+    * *_json_encoder*: encoder to encode objects to JSON. Database-specific encoders are available at ``nefertari.engine.JSONEncoder``.
diff --git a/docs/source/overview.rst → docs/source/why.rst b/docs/source/overview.rst → docs/source/why.rst
@@ -1,5 +1,5 @@
-Overview
-========
+Why Nefertari?
+==============
 
 Nefertari is a tool for making REST APIs using the Pyramid web framework.
 
@@ -29,4 +29,4 @@ By making assumptions about sane defaults, we can eliminate the need for boilerp
 
 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. Laying out a ton of boilerplate can be considered to fall into "flat is better than nested" and might be best for some teams.
+.. [#] For the record, DRF is pretty badass and we have great respect for its breadth and the hard work of its community. Laying out a ton of boilerplate can be considered to fall into "flat is better than nested" and might be best for some teams.