docs: addition of param and result sections

* Improves documentation. (addresses inveniosoftware#75)

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

docs/api.rst

@@ -25,57 +25,54 @@
 API Docs
 ========
 
+Extension
+---------
+
 .. automodule:: invenio_pidstore.ext
    :members:
-   :undoc-members:
+
+Models
+------
 
 .. automodule:: invenio_pidstore.models
    :members:
-   :undoc-members:
 
 Resolver
 --------
 
 .. automodule:: invenio_pidstore.resolver
    :members:
-   :undoc-members:
 
 
 Providers
 ---------
 
 .. automodule:: invenio_pidstore.providers
    :members:
-   :undoc-members:
 
 .. automodule:: invenio_pidstore.providers.base
    :members:
-   :undoc-members:
 
 .. automodule:: invenio_pidstore.providers.recordid
    :members:
-   :undoc-members:
 
 Minters
 -------
 
 .. automodule:: invenio_pidstore.minters
    :members:
-   :undoc-members:
 
 Fetchers
 --------
 
 .. automodule:: invenio_pidstore.fetchers
    :members:
-   :undoc-members:
 
 Exceptions
 ----------
 
 .. automodule:: invenio_pidstore.errors
    :members:
-   :undoc-members:
 
 CLI
 ---
@@ -85,4 +82,3 @@ Detailed usage documentation is available by running
 
 .. automodule:: invenio_pidstore.cli
    :members:
-   :undoc-members:

invenio_pidstore/admin.py

@@ -24,25 +24,21 @@
 from flask import current_app, url_for
 from flask_admin.contrib.sqla import ModelView
 from flask_admin.contrib.sqla.filters import FilterEqual
+from flask_babelex import gettext as _
 from markupsafe import Markup
 
 from .models import PersistentIdentifier, PIDStatus
 
 
-def _(x):
-    """Identity function for string extraction."""
-    return x
-
-
 def object_formatter(v, c, m, p):
     """Format object view link."""
     endpoint = current_app.config['PIDSTORE_OBJECT_ENDPOINTS'].get(
         m.object_type)
 
     if endpoint and m.object_uuid:
         return Markup('<a href="{0}">{1}</a>'.format(
-                url_for(endpoint, id=m.object_uuid),
-                _('View')))
+            url_for(endpoint, id=m.object_uuid),
+            _('View')))
     return ''
 
 

invenio_pidstore/ext.py

@@ -57,22 +57,36 @@ def __init__(self, app, minters_entry_point_group=None,
             self.load_fetchers_entry_point_group(fetchers_entry_point_group)
 
     def register_minter(self, name, minter):
-        """Register a minter."""
+        """Register a minter.
+
+        :param name: Minter name.
+        :param minter: The new minter.
+        """
         assert name not in self.minters
         self.minters[name] = minter
 
     def register_fetcher(self, name, fetcher):
-        """Register a fetcher."""
+        """Register a fetcher.
+
+        :param name: Fetcher name.
+        :param fetcher: The new fetcher.
+        """
         assert name not in self.fetchers
         self.fetchers[name] = fetcher
 
     def load_minters_entry_point_group(self, entry_point_group):
-        """Load minters from an entry point group."""
+        """Load minters from an entry point group.
+
+        :param entry_point_group: The entrypoint group.
+        """
         for ep in pkg_resources.iter_entry_points(group=entry_point_group):
             self.register_minter(ep.name, ep.load())
 
     def load_fetchers_entry_point_group(self, entry_point_group):
-        """Load fetchers from an entry point group."""
+        """Load fetchers from an entry point group.
+
+        :param entry_point_group: The entrypoint group.
+        """
         for ep in pkg_resources.iter_entry_points(group=entry_point_group):
             self.register_fetcher(ep.name, ep.load())
 
@@ -83,7 +97,13 @@ class InvenioPIDStore(object):
     def __init__(self, app=None,
                  minters_entry_point_group='invenio_pidstore.minters',
                  fetchers_entry_point_group='invenio_pidstore.fetchers'):
-        """Extension initialization."""
+        """Extension initialization.
+
+        :param minters_entry_point_group: The entrypoint for minters.
+            (Default: `invenio_pidstore.minters`).
+        :param fetchers_entry_point_group: The entrypoint for fetchers.
+            (Default: `invenio_pidstore.fetchers`).
+        """
         if app:
             self._state = self.init_app(
                 app, minters_entry_point_group=minters_entry_point_group,
@@ -92,7 +112,22 @@ def __init__(self, app=None,
 
     def init_app(self, app, minters_entry_point_group=None,
                  fetchers_entry_point_group=None):
-        """Flask application initialization."""
+        """Flask application initialization.
+
+        Initialize:
+
+        * The CLI commands.
+
+        * Initialize the logger (Default: `app.debug`).
+
+        * Initialize the default admin object link endpoint.
+            (Default: `{"rec": "recordmetadata.details_view"}` if
+            `invenio-records` is installed, otherwise `{}`).
+
+        * Register the `pid_exists` template filter.
+
+        * Initialize extension state.
+        """
         # Initialize CLI
         app.cli.add_command(cmd)
 

invenio_pidstore/fetchers.py

@@ -22,7 +22,24 @@
 # waive the privileges and immunities granted to it by virtue of its status
 # as an Intergovernmental Organization or submit itself to any jurisdiction.
 
-"""Persistent identifier minters."""
+"""Persistent identifier fetchers.
+
+A proper fetcher is defined as a function that return a
+:data:`invenio_pidstore.fetchers.FetchedPID` instance.
+
+E.g.
+
+.. code-block:: python
+
+    def my_fetcher(record_uuid, data):
+        return FetchedPID(
+            provider=MyRecordIdProvider,
+            pid_type=MyRecordIdProvider.pid_type,
+            pid_value=extract_pid_value(data),
+        )
+
+To see more about providers see :mod:`invenio_pidstore.providers`.
+"""
 
 from __future__ import absolute_import, print_function
 
@@ -31,10 +48,16 @@
 from .providers.recordid import RecordIdProvider
 
 FetchedPID = namedtuple('FetchedPID', ['provider', 'pid_type', 'pid_value'])
+"""A pid fetcher."""
 
 
 def recid_fetcher(record_uuid, data):
-    """Fetch a record's identifiers."""
+    """Fetch a record's identifiers.
+
+    :param record_uuid: The record UUID.
+    :param data: The record metadata.
+    :returns: A :data:`invenio_pidstore.fetchers.FetchedPID` instance.
+    """
     return FetchedPID(
         provider=RecordIdProvider,
         pid_type=RecordIdProvider.pid_type,

invenio_pidstore/minters.py

@@ -30,7 +30,29 @@
 
 
 def recid_minter(record_uuid, data):
-    """Mint record identifiers."""
+    """Mint record identifiers.
+
+    This is a minter specific for records.
+    With the help of
+    :class:`invenio_pidstore.providers.recordid.RecordIdProvider`, it creates
+    the PID instance with `rec` as predefined `object_type`.
+
+    Procedure followed:
+
+    #. If a `control_number` field is already there, a `AssertionError`
+    exception is raised.
+
+    #. The provider is initialized with the help of
+    :class:`invenio_pidstore.providers.recordid.RecordIdProvider`.
+    It's called with default value 'rec' for `object_type` and `record_uuid`
+    variable for `object_uuid`.
+
+    #. The new `id_value` is stored inside `data` as `control_number` field.
+
+    :param record_uuid: The record UUID.
+    :param data: The record metadata.
+    :returns: A fresh `invenio_pidstore.models.PersistentIdentifier` instance.
+    """
     assert 'control_number' not in data
     provider = RecordIdProvider.create(
         object_type='rec', object_uuid=record_uuid)