docs: addition of param and result sections

invenio_records_ui/config.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+#
+# This file is part of Invenio.
+# Copyright (C) 2016 CERN.
+#
+# Invenio is free software; you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version.
+#
+# Invenio is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Invenio; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+# MA 02111-1307, USA.
+#
+# In applying this license, CERN does not
+# waive the privileges and immunities granted to it by virtue of its status
+# as an Intergovernmental Organization or submit itself to any jurisdiction.
+
+"""Flask extension for Invenio-Records-UI."""
+
+from __future__ import absolute_import, print_function
+
+
+RECORDS_UI_BASE_TEMPLATE = "invenio_records_ui/base.html"
+"""Configure the basic record template."""
+
+RECORDS_UI_TOMBSTONE_TEMPLATE = "invenio_records_ui/tombstone.html"
+"""Configure the tombstone template."""
+
+RECORDS_UI_DEFAULT_PERMISSION_FACTORY = ("invenio_records.permissions:"
+                                         "read_permission_factory")
+"""Configure the default permission factory."""
+
+RECORDS_UI_LOGIN_ENDPOINT = "security.login"
+"""Endpoint where redirect the user if login is required."""
+
+RECORDS_UI_ENDPOINTS = {
+    "recid": {
+        "pid_type": "recid",
+        "route": "/records/<pid_value>",
+        "template": "invenio_records_ui/detail.html",
+    }
+}
+"""Default UI endpoints loaded.
+
+This option can be overwritten to describe the endpoints of the different
+record types.
+
+Each element on the dictionary represent a independent endpoint.
+
+The structure of the dictionary is as follows:
+
+.. code-block:: python
+
+    def my_view(pid, record, template=None):
+        return render_template(template, pid=pid, record=record)
+
+
+    RECORDS_UI_ENDPOINTS = {
+        "<endpoint-name>": {
+            "pid_type": "<record-pid-type>",
+            "route": "/records/<pid_value>",
+            "template": "invenio_records_ui/detail.html",
+            "permission_factory_imp": ("invenio_records.permissions:"
+                                       "read_permission_factory")
+            "view_imp": my_view,
+            "record_class": "invenio_records.api:Record",
+            "methods": ["GET", "POST", "PUT", "DELETE"],
+        },
+        ...
+    }
+
+:param pid_type: Persistent identifier type for endpoint. Required.
+
+:param route: URL route (must include ``<pid_value>`` pattern). Required.
+
+:param template: Template to render.
+    (Default: ``invenio_records_ui/detail.html``)
+
+:param permission_factory_imp: Import path to factory that creates a
+        permission object for a given record.
+
+:param view_imp: Import path to view function. (Default: ``None``)
+
+:param record_class: Import path of record class.
+    (Default: ``invenio_records.api:Record``)
+
+:param methods: List of methods supported. (Default: ``['GET']``)
+"""

invenio_records_ui/ext.py

@@ -28,14 +28,18 @@
 
 from werkzeug.utils import import_string
 
+from . import config
 from .views import create_blueprint
 
 
 class _RecordUIState(object):
     """Record UI state."""
 
     def __init__(self, app):
-        """Initialize state."""
+        """Initialize state.
+
+        :param app: The Flask application.
+        """
         self.app = app
         self._permission_factory = None
 
@@ -56,12 +60,18 @@ class InvenioRecordsUI(object):
     """
 
     def __init__(self, app=None):
-        """Extension initialization."""
+        """Extension initialization.
+
+        :param app: The Flask application. (Default: ``None``)
+        """
         if app:
             self.init_app(app)
 
     def init_app(self, app):
-        """Flask application initialization."""
+        """Flask application initialization.
+
+        :param app: The Flask application.
+        """
         self.init_config(app)
 
         # Register records blueprints
@@ -71,31 +81,10 @@ def init_app(self, app):
         app.extensions['invenio-records-ui'] = _RecordUIState(app)
 
     def init_config(self, app):
-        """Initialize configuration on application."""
-        app.config.setdefault(
-            "RECORDS_UI_BASE_TEMPLATE",
-            app.config.get("BASE_TEMPLATE",
-                           "invenio_records_ui/base.html"))
-
-        # Tombstones
-        app.config.setdefault(
-            "RECORDS_UI_TOMBSTONE_TEMPLATE",
-            "invenio_records_ui/tombstone.html")
-
-        app.config.setdefault(
-            "RECORDS_UI_DEFAULT_PERMISSION_FACTORY",
-            "invenio_records.permissions:read_permission_factory")
-
-        app.config.setdefault("RECORDS_UI_LOGIN_ENDPOINT", "security.login")
-
-        # Set up endpoints for viewing records.
-        app.config.setdefault(
-            "RECORDS_UI_ENDPOINTS",
-            dict(
-                recid=dict(
-                    pid_type='recid',
-                    route='/records/<pid_value>',
-                    template='invenio_records_ui/detail.html',
-                ),
-            )
-        )
+        """Initialize configuration on application.
+
+        :param app: The Flask application.
+        """
+        for k in dir(config):
+            if k.startswith('RECORDS_UI_'):
+                app.config.setdefault(k, getattr(config, k))

invenio_records_ui/views.py

@@ -52,6 +52,7 @@ def create_blueprint(endpoints):
 
     :param endpoints: Dictionary of endpoints to be installed. See usage
         documentation for further details.
+    :returns: The initialized blueprint.
     """
     blueprint = Blueprint(
         'invenio_records_ui',
@@ -86,12 +87,14 @@ def create_url_rule(endpoint, route=None, pid_type=None, template=None,
     :param endpoint: Name of endpoint.
     :param route: URL route (must include ``<pid_value>`` pattern). Required.
     :param pid_type: Persistent identifier type for endpoint. Required.
-    :param template: Template to render. Defaults to
-        ``invenio_records_ui/detail.html``.
+    :param template: Template to render.
+        (Default: ``invenio_records_ui/detail.html``)
     :param permission_factory_imp: Import path to factory that creates a
         permission object for a given record.
-    :param view_imp: Import path to view function. Default: None.
-    :returns: a dictionary that can be passed as keywords arguments to
+    :param view_imp: Import path to view function. (Default: ``None``)
+    :param record_class: Name of the record API class.
+    :param methods: Method allowed for the endpoint.
+    :returns: A dictionary that can be passed as keywords arguments to
         ``Blueprint.add_url_rule``.
     """
     assert route
@@ -136,11 +139,23 @@ def record_view(pid_value=None, resolver=None, template=None,
     - ``pid``
     - ``record``.
 
+    Procedure followed:
+
+    #. PID and record are resolved.
+
+    #. Permission are checked.
+
+    #. ``view_method`` is called.
+
     :param pid_value: Persistent identifier value.
     :param resolver: An instance of a persistent identifier resolver. A
         persistent identifier resolver takes care of resolving persistent
         identifiers into internal objects.
     :param template: Template to render.
+    :param permission_factory: Permission factory called to check if user has
+        enough power to execute the action.
+    :param view_method: Function that is called.
+    :returns: Tuple (pid object, record object).
     """
     try:
         pid, record = resolver.resolve(pid_value)
@@ -186,6 +201,11 @@ def default_view_method(pid, record, template=None):
     """Default view method.
 
     Sends record_viewed signal and renders template.
+
+    :param pid: PID object.
+    :param record: Record object.
+    :param template: Template to render.
+    :returns: The rendered template.
     """
     record_viewed.send(
         current_app._get_current_object(),