docs: improve documentation

* Improves documentation. (addresses inveniosoftware#95)

Signed-off-by: Leonardo Rossi <leonardo.r@cern.ch>

invenio_deposit/api.py

@@ -56,7 +56,11 @@
 
 
 def index(method=None, delete=False):
-    """Update index."""
+    """Decorator to update index.
+
+    :params method: Function wrapped.
+    :params delete: If `True` delete the indexed record.
+    """
     if method is None:
         return partial(index, delete=delete)
 
@@ -76,7 +80,11 @@ def wrapper(self_or_cls, *args, **kwargs):
 
 
 def has_status(method=None, status='draft'):
-    """Check that deposit has defined status (default: draft)."""
+    """Check that deposit has a defined status (default: draft).
+
+    :param method: Function executed if record has a defined status.
+    :params status: Defined status to check.
+    """
     if method is None:
         return partial(has_status, status=status)
 
@@ -91,7 +99,13 @@ def wrapper(self, *args, **kwargs):
 
 
 def preserve(method=None, result=True, fields=None):
-    """Preserve fields in deposit."""
+    """Preserve fields in deposit.
+
+    :params method: Function to execute.
+    :params result: If `True` returns the result of method execution,
+        otherwise `self`.
+    :params fields: List of fields to preserve (default is `_deposit`).
+    """
     if method is None:
         return partial(preserve, result=result, fields=fields)
 
@@ -181,13 +195,31 @@ def merge_with_published(self):
 
     @index
     def commit(self, *args, **kwargs):
-        """Store changes on current instance in database."""
+        """Store changes on current instance in database and index it."""
         return super(Deposit, self).commit(*args, **kwargs)
 
     @classmethod
     @index
     def create(cls, data, id_=None):
-        """Create a deposit."""
+        """Create a deposit.
+
+        Initialize the follow information inside the deposit:
+
+        .. code-block:: python
+
+            deposit['_deposit'] = {
+                'id': pid_value,
+                'status': 'draft',
+                'owners': [user_id],
+                'created_by': user_id,
+            }
+
+        The deposit index is updated.
+
+        :param data: Input dictionary to fill the deposit.
+        :param id_: Default uuid for the deposit.
+        :returns: The new created deposit.
+        """
         data.setdefault('$schema', current_jsonschemas.path_to_url(
             current_app.config['DEPOSIT_DEFAULT_JSONSCHEMA']
         ))
@@ -258,10 +290,39 @@ def _publish_edited(self):
         record = record.__class__(data, model=record.model)
         return record
 
-    # No need for indexing as it calls self.commit()
     @has_status
     def publish(self, pid=None, id_=None):
-        """Publish a deposit."""
+        """Publish a deposit.
+
+        If it's the first time:
+
+        * it calls the minter and set the following meta information inside
+            the deposit:
+
+        .. code-block:: python
+
+            deposit['_deposit'] = {
+                'type': pid_type,
+                'value': pid_value,
+                'revision_id': 0,
+            }
+
+        * Dumps all the information inside the deposit
+
+        * Make a snapshot of the files.
+
+        Otherwise, published the new edited version.
+        In this case, if in the mainwhile someone already published a new
+        version, it'll try to merge the changes with the latest version.
+
+        Note: no need for indexing as it calls self.commit().
+
+        Status required: `draft`.
+
+        :params pid: Force the new pid value.
+        :params id_: Force the new uuid value as deposit id.
+        :returns: Returns itself.
+        """
         pid = pid or self.pid
 
         if not pid.is_registered():
@@ -289,7 +350,34 @@ def _prepare_edit(self, record):
     @has_status(status='published')
     @index
     def edit(self, pid=None):
-        """Edit deposit."""
+        """Edit deposit.
+
+        #. The signal
+        class:`invenio_records.signals.before_record_update` is sent before the
+        edit execution.
+
+        #. The following meta information are saved inside the deposit:
+
+        .. code-block:: python
+
+            deposit['_deposit']['pid'] = record.revision_id
+            deposit['_deposit']['status'] = 'draft'
+            deposit['$schema'] = deposit_schema_from_record_schema
+
+        #. The signal
+        class:`invenio_records.signals.after_record_update` is sent after the
+        edit execution.
+
+        #. The deposit index is updated.
+
+        Status required: `published`.
+
+        Note: the process fails if the pid has status
+        class:`invenio_pidstore.models.PIDStatus.REGISTERED`.
+
+        :params pid: Force a pid object.
+        :returns: A new Deposit object.
+        """
         pid = pid or self.pid
 
         with db.session.begin_nested():
@@ -310,7 +398,32 @@ def edit(self, pid=None):
     @has_status
     @index
     def discard(self, pid=None):
-        """Discard deposit changes."""
+        """Discard deposit changes.
+
+        #. The signal
+        class:`invenio_records.signals.before_record_update` is sent before the
+        edit execution.
+
+        #. It restores the last published version.
+
+        #. The following meta information are saved inside the deposit:
+
+        .. code-block:: python
+
+            deposit['_deposit']['status'] = 'draft'
+            deposit['$schema'] = deposit_schema_from_record_schema
+
+        #. The signal
+        class:`invenio_records.signals.after_record_update` is sent after the
+        edit execution.
+
+        #. The deposit index is updated.
+
+        Status required: `draft`.
+
+        :params pid: Force a pid object.
+        :returns: A new Deposit object.
+        """
         pid = pid or self.pid
 
         with db.session.begin_nested():
@@ -330,7 +443,14 @@ def discard(self, pid=None):
     @has_status
     @index(delete=True)
     def delete(self, force=True, pid=None):
-        """Delete deposit."""
+        """Delete deposit.
+
+        Status required: `draft`.
+
+        :param force: Force deposit delete
+        :param pid: Force pid object
+        :returns A new Deposit object.
+        """
         pid = pid or self.pid
 
         if self['_deposit'].get('pid'):
@@ -342,19 +462,34 @@ def delete(self, force=True, pid=None):
     @has_status
     @preserve(result=False)
     def clear(self, *args, **kwargs):
-        """Clear only drafts."""
+        """Clear only drafts.
+
+        Status required: `draft`.
+
+        Meta information inside `_deposit` are preserved.
+        """
         super(Deposit, self).clear(*args, **kwargs)
 
     @has_status
     @preserve(result=False)
     def update(self, *args, **kwargs):
-        """Update only drafts."""
+        """Update only drafts.
+
+        Status required: `draft`.
+
+        Meta information inside `_deposit` are preserved.
+        """
         super(Deposit, self).update(*args, **kwargs)
 
     @has_status
     @preserve
     def patch(self, *args, **kwargs):
-        """Patch only drafts."""
+        """Patch only drafts.
+
+        Status required: `draft`.
+
+        Meta information inside `_deposit` are preserved.
+        """
         return super(Deposit, self).patch(*args, **kwargs)
 
     def _create_bucket(self):
@@ -365,7 +500,10 @@ def _create_bucket(self):
 
     @property
     def files(self):
-        """Add validation on ``sort_by`` method."""
+        """List of Files inside the deposit.
+
+        Add validation on ``sort_by`` method.
+        """
         files_ = super(Deposit, self).files
 
         if files_: