docs: improve documentation

* Improves documentation. (addresses inveniosoftware#99)

Signed-off-by: Leonardo Rossi <[email protected]>

invenio_records_rest/config.py

@@ -58,16 +58,81 @@ def _(x):
         max_result_window=10000,
     ),
 )
+"""Default REST endpoints loaded.
+
+This option can be overwritten to describe the endpoints of the different
+record types.
+Each endpoint is in charge of managing all its CRUD operations (GET, POST,
+PUT, DELETE, ..).
+
+The structure of the dictionary is as follows:
+
+    RECORDS_REST_ENDPOINTS = {
+        "record-pid-type": {
+            "pid_type": "record-pid-type",
+            "pid_minter": "registered-minter-name",  # see invenio-pidstore
+            "pid_fetcher": "registered-pid-fetcher",  # see invenio-pidstore
+            "search_class": "mypackage.utils:mysearchclass",
+            "search_index": "elasticsearch-index-name",
+            "search_type": "elasticsearch-doc-type",
+            "record_serializers": {
+                "application/json": "mypackage.utils:my_json_serializer"
+            },
+            "search_serializers": {
+                "application/json": "mypackage.utils:my_json_search_serializer"
+            },
+            "list_route": "/records/",
+            "item_route": ""/records/<pid(recid):pid_value>"",
+            "default_media_type": "application/json",
+            "max_result_window": 10000,
+        },
+        ...
+    }
+
+:param pid_type: It specifies the record pid type. It's used also to build the
+    endpoint name. Required.
+    E.g. ``url_for('record-pid-type_list')`` to point to the records list.
+
+:param pid_minter: It identifies the registered minter name
+    (see class:`invenio_pidstore:_PIDStoreState`). Required.
+
+:param pid_fetcher: It identifies the registered fetcher name
+    (see class:`invenio_pidstore:_PIDStoreState`). Required.
+
+:param search_class: The default search class is
+    class:`invenio_search.api.RecordsSearch`.
+    For more information about resource loading, see
+    class:`elasticsearch_dsl.Search`.
+
+:param search_type: You can specify Optional.
+
+:param record_serializers: it contains the list of record serializers for all
+    supported format.
+
+:param search_serializers: it contains the list of records serializers for all
+    supported format. This configuration differ from the previous because in
+    this case it handle a list of records resulted by a search query instead of
+    a single record.
+
+:param list_route: base URL for the records endpoint.
+
+:param item_route: URL template for a single record.
+
+:param max_result_window: maximum total number of records retrieved from a
+    query.
+"""
 
 RECORDS_REST_DEFAULT_LOADERS = {
     'application/json': lambda: request.get_json(),
     'application/json-patch+json': lambda: request.get_json(force=True),
 }
 """Default data loaders per request mime type.
 
-This option can be overritten in each REST endpoint as follows::
+This option can be overritten in each REST endpoint as follows:
 
-    {
+.. code-block:: python
+
+    RECORDS_REST_ENDPOINTS = {
         "recid": {
             ...
             "record_loaders": {
@@ -97,7 +162,7 @@ def _(x):
 )
 """Sort options for default sorter factory.
 
-The structure of the dictionary is as follows::
+The structure of the dictionary is as follows:
 
     {
         "<index or index alias>": {
@@ -124,7 +189,17 @@ def _(x):
         noquery='mostrecent',
     )
 )
-"""Default sort option per index with/without query string."""
+"""Default sort option per index with/without query string.
+
+The structure of the dictionary is as follows:
+
+    {
+        "<index or index alias>": {
+            "query": "<default-sort-if-a-query-is-passed-from-url>",
+            "noquery": "<default-sort-if-no-query-in-passed-from-url>"
+        }
+    }
+"""
 
 RECORDS_REST_FACETS = dict(
     records=dict(
@@ -138,7 +213,7 @@ def _(x):
 )
 """Facets per index for the default facets factory.
 
-The structure of the dictionary is as follows::
+The structure of the dictionary is as follows:
 
     {
         "<index or index alias>": {
@@ -159,6 +234,13 @@ def _(x):
 """
 
 RECORDS_REST_DEFAULT_CREATE_PERMISSION_FACTORY = deny_all
+"""Default crete permission factory: reject any request."""
+
 RECORDS_REST_DEFAULT_READ_PERMISSION_FACTORY = check_elasticsearch
+"""Default read permission factory: check if the record exists."""
+
 RECORDS_REST_DEFAULT_UPDATE_PERMISSION_FACTORY = deny_all
+"""Default update permission factory: reject any request."""
+
 RECORDS_REST_DEFAULT_DELETE_PERMISSION_FACTORY = deny_all
+"""Default delete permission factory: reject any request."""

invenio_records_rest/errors.py

@@ -34,7 +34,7 @@
 # Search
 #
 class MaxResultWindowRESTError(RESTException):
-    """Maximum number of results passed."""
+    """Maximum number of passed results have been reached."""
 
     code = 400
     description = 'Maximum number of results have been reached.'

invenio_records_rest/facets.py

@@ -34,14 +34,25 @@
 
 
 def terms_filter(field):
-    """Create a term filter."""
+    """Create a term filter.
+
+    :param field: field name.
+    :returns: function that returns the Terms query.
+    """
     def inner(values):
         return Q('terms', **{field: values})
     return inner
 
 
 def range_filter(field, start_date_math=None, end_date_math=None, **kwargs):
-    """Create a range filter."""
+    """Create a range filter.
+
+    :param field: field name
+    :param start_date_math: starting date
+    :param end_date_math: ending date
+    :param kwargs: addition arguments passed to the Range query.
+    :returns: function that returns the Range query.
+    """
     def inner(values):
         if len(values) != 1 or values[0].count('--') != 1 or values[0] == '--':
             raise RESTValidationError(
@@ -121,7 +132,13 @@ def _aggregations(search, definitions):
 
 
 def default_facets_factory(search, index):
-    """Add facets to query."""
+    """Add a default facets to query.
+
+    :param search: basic search object
+    :param index: index name
+    :returns: a tuple containing the new search object and a dictionary with
+    all fields and values used.
+    """
     urlkwargs = MultiDict()
 
     facets = current_app.config['RECORDS_REST_FACETS'].get(index)