working on documentation for 0.2.2

ramses-tech · May 15, 2015 · 42e95ba · 42e95ba
1 parent 6636da7
commit 42e95ba
Show file tree

Hide file tree

Showing 11 changed files with 223 additions and 174 deletions.
diff --git a/docs/source/acls.rst b/docs/source/acls.rst
diff --git a/docs/source/auth.rst b/docs/source/auth.rst
@@ -0,0 +1,38 @@
+Authentication & Security
+=========================
+
+Set `auth = true` in you .ini file to enable authentication.
+
+Ticket Auth
+-----------
+
+Nefertari currently supports the default Pyramid "auth ticket" cookie method of authentication.
+
+Token Auth
+----------
+
+(under development)
+
+Visible fields in views
+-----------------------
+
+You can control which fields to display to both authenticated users and unauthenticated users by defining `_auth_fields` and `_public_fields` respectively in your models.
+
+ACL API
+-------
+
+For authorizing access to specific resources, Nefertari uses standard Pyramid access control lists. `See the documentation on Pyramid ACLs <http://docs.pylonsproject.org/projects/pyramid/en/1.5-branch/narr/security.html>`_ to understand how to extend and customize them.
+
+.. automodule:: nefertari.acl
+    :members:
+
+CORS
+----
+
+To enable CORS headers, set the following lines in your .ini file:
+
+.. code-block:: ini
+
+    cors.enable = true
+    cors.allow_origins = http://localhost
+    cors.allow_credentials = true
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -1,6 +1,9 @@
 Changelog
 =========
 
+* :release:`0.2.2 <2015-05-15>`
+* :support:`0` Step-by-step Getting started guide
+
 * :release:`0.2.1 <2015-04-21>`
 * :support:`0` Specify any field as primary, and have it respected by all relations endpoints.
 * :feature:`0` Added DictField type.
@@ -13,4 +16,4 @@ Changelog
 * :support:`0` Improved docs.
 
 * :release:`0.1.1 <2015-04-01>`
-* :support:`0` Initial release after two years of development as "Presto". Now with database engines! Originally extracted and generalized from the Brandicted API which only used MongoDB.
+* :support:`0` Initial release after two years of development as "Presto". Now with database engines! Originally extracted and generalized from the Brandicted API which only used MongoDB.
diff --git a/docs/source/database_backends.rst b/docs/source/database_backends.rst
@@ -1,25 +1,51 @@
 Database Backends
 =================
 
-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.
+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.
 
-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:
 
-Each Nefertari engine is developed in its own repository:
+* `Nefertari SQLA Engine <https://github.com/brandicted/nefertari-sqla>`_
+* `Nefertari MongoDB Engine <https://github.com/brandicted/nefertari-mongodb>`_
 
-* `SQLA Engine <http://nefertari-sqla.readthedocs.org/en/latest/>`_
-* `MongoDB Engine <http://nefertari-mongodb.readthedocs.org/en/latest/>`_
+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.
 
-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.
+Field abstractions
+-------------------
 
+* BigIntegerField
+* BooleanField
+* DateField
+* DateTimeField
+* ChoiceField
+* FloatField
+* IntegerField
+* IntervalField
+* BinaryField
+* DecimalField
+* PickleField
+* SmallIntegerField
+* StringField
+* TextField
+* TimeField
+* UnicodeField
+* UnicodeTextField
+* Relationship
+* IdField
+* ForeignKeyField
+* ListField
+* DictField
 
 Wrapper API
 -----------
 
-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>`_.
+Both of the database engines used by Nefertari implement a similar "Wrapper API" for developers to use within a Nefertari project. You can read more about either engine's in their respective documentation:
+
+ * `Nefertari SQLA documentation <http://nefertari-sqla.readthedocs.org/en/stable/>`_
+ * `Nefertari MongoDB documentation <http://nefertari-mongodb.readthedocs.org/en/stable/>`_
 
 **BaseMixin**
-    Mixin with a most of the API of *BaseDocument*. *BaseDocument* subclasses from this mixin.
+    Mixin with most of the API of *BaseDocument*. *BaseDocument* subclasses from this mixin.
 
 **BaseDocument**
     Base for regular models defined in your application. Just subclass it to define your model's fields. Relevant attributes:
@@ -50,27 +76,3 @@ Both of the database engines used by Nefertari implement a similar "Wrapper API"
 
 **relationship_cls(field, model_cls)**
     Return class which is pointed to by relationship field *field* from model *model_cls*.
-
-Field abstractions
--------------------
-
-* BigIntegerField
-* BooleanField
-* DateField
-* DateTimeField
-* ChoiceField
-* FloatField
-* IntegerField
-* IntervalField
-* BinaryField
-* DecimalField
-* PickleField
-* SmallIntegerField
-* StringField
-* TextField
-* TimeField
-* UnicodeField
-* UnicodeTextField
-* Relationship
-* PrimaryKeyField
-* ForeignKeyField
diff --git a/docs/source/development_tools.rst b/docs/source/development_tools.rst
@@ -2,7 +2,7 @@ Development Tools
 =================
 
 Indexing in ElasticSearch
------------------------------
+-------------------------
 
 ``nefertari.index`` console script can be used to manually (re-)index models from your database engine to ElasticSearch.
 
@@ -13,7 +13,7 @@ You can run it like so::
 The available options are:
 
 --config        specify ini file to use (required)
---models        list of dotted paths of models to index. Models must be subclasses of ESBaseDocument.
+--models        list of models to index (e.g. User). Models must subclass ESBaseDocument.
 --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