Improve docs

README.md

@@ -102,11 +102,17 @@ by front end without aggregation.
 
 ```python
 
-def CityBase(DomainModel):
-    _collection_name = "cities"
-
-class City(CityBase):
-    _schema_cls = CitySchema 
+from flask_boiler.domain_model import DomainModel
+from flask_boiler import attrs
+
+class City(DomainModel):
+
+    city_name = attrs.bproperty()
+    country = attrs.bproperty()
+    capital = attrs.bproperty()
+
+    class Meta:
+        collection_name = "City"
 
 City.new(
         doc_id='SF',
@@ -144,46 +150,6 @@ p.save()
 
 See ```examples/relationship_example.py```
 
-
-### Context Management
-In `__init__` of your project source root:
-```python
-import os
-
-from flask_boiler import context
-from flask_boiler import config
-
-Config = config.Config
-
-testing_config = Config(app_name="your_app_name",
-                        debug=True,
-                        testing=True,
-                        certificate_path=os.path.curdir + "/../your_project/config_jsons/your_certificate.json")
-
-CTX = context.Context
-CTX.read(testing_config)
-```
-
-Note that initializing `Config` with `certificate_path` is unstable and
-may be changed later.
-
-In your project code,
-
-```python
-from flask_boiler import context
-
-CTX = context.Context
-
-# Retrieves firestore database instance 
-CTX.db
-
-# Retrieves firebase app instance 
-CTX.firebase_app
-
-```
-
-
-
 ### Automatically Generated Swagger Docs
 You can enable auto-generated swagger docs. See: `examples/view_example.py`
 

context_management.md

@@ -0,0 +1,60 @@
+# Context Management 
+
+
+## Auto Configuration with boiler.yaml
+
+Provide authentication credentials to flask-boiler by moving the json certificate file 
+to your project directory and specify the path in ```boiler.yaml``` 
+in your current working directory. 
+
+```yaml
+app_name: "<Your Firebase App Name>"
+debug: True
+testing: True
+certificate_filename: "<File Name of Certificate JSON>"
+```
+
+In ```__init__``` of your project source root: 
+```python
+from flask_boiler.context import Context as CTX
+
+CTX.load()
+```
+
+## Manual Configuration 
+In `__init__` of your project source root:
+```python
+import os
+
+from flask_boiler import context
+from flask_boiler import config
+
+Config = config.Config
+
+testing_config = Config(app_name="your_app_name",
+                        debug=True,
+                        testing=True,
+                        certificate_path=os.path.curdir + "/../your_project/config_jsons/your_certificate.json")
+
+CTX = context.Context
+CTX.read(testing_config)
+```
+
+Note that initializing `Config` with `certificate_path` is unstable and
+may be changed later.
+
+In your project code,
+
+```python
+from flask_boiler import context
+
+CTX = context.Context
+
+# Retrieves firestore database instance 
+CTX.db
+
+# Retrieves firebase app instance 
+CTX.firebase_app
+
+```
+

docs/apidoc/modules.rst

@@ -54,3 +54,19 @@ Query Delta View Mediator
    :inherited-members:
    :undoc-members:
    :show-inheritance:
+
+Context
+----------------------------
+
+.. autoclass:: flask_boiler.context.Context
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Auth
+-------------------------
+
+.. automodule:: flask_boiler.auth
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/context-management.rst

@@ -1,40 +1 @@
-.. _context-management:
-
-Context Management
-==================
-
-In ```__init__``` of your project source root:
-
-.. code-block:: python
-
-    import os
-
-    from flask_boiler import context
-    from flask_boiler import config
-
-    Config = config.Config
-
-    testing_config = Config(app_name="your_app_name",
-                            debug=True,
-                            testing=True,
-                            certificate_path=os.path.curdir + "/../your_project/config_jsons/your_certificate.json")
-
-    CTX = context.Context
-    CTX.read(testing_config)
-
-Note that initializing ```Config``` with ```certificate_path``` is unstable and
-may be changed later.
-
-In your project code,
-
-.. code-block:: python
-
-    from flask_boiler import context
-
-    CTX = context.Context
-
-    # Retrieves firestore database instance
-    CTX.db
-
-    # Retrieves firebase app instance
-    CTX.firebase_app
+.. mdinclude:: ../context_management.md

flask_boiler/collection_mixin.py

@@ -14,9 +14,8 @@ def _doc_ref_from_id(cls, doc_id):
     def collection_name(self):
         """ Returns the root collection name of the class of objects.
                 If cls._collection_name is not specified, then the collection
-                name will be inferred from the class name.
-
-        :return:
+                name will be inferred from the class name. Note that different
+                types of objects may share one collection.
         """
         # if type(self) == FirestoreObject:
         #     raise ValueError("collection_name is read from class name, "
@@ -32,8 +31,6 @@ def _get_collection_name(cls):
     @property
     def collection(self):
         """ Returns the firestore collection of the current object
-
-        :return:
         """
         return self._get_collection()
 
@@ -46,6 +43,5 @@ def ref_from_id(cls, doc_id):
         """ Returns a Document Reference from doc_id supplied.
 
         :param doc_id: Document ID
-        :return:
         """
         return cls._get_collection().document(document_id=doc_id)

flask_boiler/context.py

@@ -22,6 +22,13 @@
 
 
 class Context:
+    """ Context Singleton for Firestore, Firebase and Celery app.
+
+        Example:
+
+
+    """
+
     firebase_app: firebase_admin.App = None
     db: firestore.Client = None
     config: Config = None

flask_boiler/firestore_object.py

@@ -31,9 +31,8 @@ def doc_ref(self) -> DocumentReference:
         raise NotImplementedError
 
     @property
-    def doc_ref_str(self):
-        """
-        Used for serializing the object
+    def doc_ref_str(self) -> str:
+        """ Serializes to doc_ref field.
         """
         return self.doc_ref.path
 
@@ -43,8 +42,7 @@ def get(cls, *, doc_ref=None, transaction=None, **kwargs):
 
         :param doc_ref:
         :param transaction:
-        :param kwargs:
-        :return:
+        :param kwargs: Keyword arguments to be forwarded to from_dict
         """
         if transaction is None:
             snapshot = doc_ref.get()
@@ -61,7 +59,6 @@ def from_snapshot(cls, snapshot=None):
         """ Deserializes an object from a Document Snapshot.
 
         :param snapshot: Firestore Snapshot
-        :return:
         """
         obj = snapshot_to_obj(snapshot=snapshot, super_cls=cls)
         return obj
@@ -73,7 +70,6 @@ def save(self, transaction: Transaction = None, doc_ref=None, save_rel=True):
         :param doc_ref: override save with this doc_ref
         :param save_rel: If true, objects nested in this
             object will be saved to the Firestore.
-        :return:
         """
         if doc_ref is None:
             doc_ref = self.doc_ref
@@ -86,11 +82,10 @@ def save(self, transaction: Transaction = None, doc_ref=None, save_rel=True):
             transaction.set(reference=doc_ref,
                             document_data=d)
 
-    def delete(self, transaction: Transaction = None):
+    def delete(self, transaction: Transaction = None) -> None:
         """ Deletes and object from Firestore.
 
-        :param transaction:
-        :return:
+        :param transaction: Firestore Transaction
         """
         if transaction is None:
             self.doc_ref.delete()
@@ -182,15 +177,20 @@ def nest_relationship(val: RelationshipReference):
                 val, to_get=to_get, transaction=transaction)
 
     @classmethod
-    def from_dict(cls, d, to_get=True, must_get=False, transaction=None, **kwargs):
+    def from_dict(
+            cls,
+            d,
+            to_get=True,
+            must_get=False,
+            transaction=None,
+            **kwargs):
         """ Deserializes an object from a dictionary.
 
         :param d: a dictionary representation of an object generated
             by `to_dict` method.
         :param transaction: Firestore transaction for retrieving
             related documents, and for saving this object.
-        :param kwargs:
-        :return:
+        :param kwargs: Keyword arguments to be forwarded to new
         """
 
         super_cls, obj_cls = cls, cls

flask_boiler/primary_object.py

@@ -27,25 +27,16 @@ class PrimaryObject(FirestoreObject, QueryMixin, CollectionMixin,
     the document will be stored in and accessed from
             self.collection.document(doc_id)
 
-    Attributes
-    ----------
-    _collection_name : str
-        the name of the collection for the object. Note that different
-            types of objects may share one collection.
-
     """
 
-    # Abstract property: MUST OVERRIDE
-    # TODO: add abstract property decorator
     _collection_name = None
 
     @classmethod
     def get_schema_cls(cls):
-        """ Returns schema_cls or the union of all schemas
-                of subclasses. Should only be used on the root
-                DomainModel. Does not cache the result.
+        """ Returns schema_cls or the union of all schemas of subclasses.
+                Should only be used on the root DomainModel. Does not
+                cache the result.
 
-        :return:
         """
         d = dict()
         if super().get_schema_cls() is None:
@@ -69,17 +60,13 @@ def __init__(self, doc_id=None, doc_ref=None, **kwargs):
 
     @property
     def doc_id(self):
-        """
-
-        :return: Document ID
+        """ Returns Document ID
         """
         return self.doc_ref.id
 
     @property
     def doc_ref(self):
-        """
-
-        :return: Document Reference
+        """ Returns Document Reference
         """
         if self._doc_ref is None:
             self._doc_ref = self.collection.document(random_id())
@@ -89,10 +76,20 @@ def doc_ref(self):
 
     @classmethod
     def new(cls, doc_id=None, doc_ref=None, **kwargs):
-        """
-        Creates an instance of object and assign a firestore
-            reference with random id to the instance.
-        :return:
+        """ Creates an instance of object and assign a firestore reference
+        with random id to the instance. This is similar to the use
+        of "new" in Java. It is recommended that you use "new" to
+        initialize an object, rather than the native initializer.
+        Values are initialized based on the order that they are
+        declared in the schema.
+
+        :param: doc_id: Document ID
+        :param: doc_ref: Document Reference
+        :param allow_default: if set to False, an error will be
+            raised if value is not provided for a field.
+        :param kwargs: keyword arguments to pass to the class
+            initializer.
+        :return: the instance created
         """
         if doc_ref is None:
             if doc_id is None:
@@ -110,7 +107,6 @@ def get(cls, *, doc_ref_str=None, doc_ref=None, doc_id=None,
         :param doc_ref: DocumentReference
         :param doc_id: gets the instance from self.collection.document(doc_id)
         :param transaction: firestore transaction
-        :return:
         """
 
         if doc_ref_str is not None: