docs: addition of method documentation

* Improves method documentation. (addresses inveniosoftware#16)

Signed-off-by: Javier Delgado [email protected]

docs/api.rst

@@ -27,3 +27,7 @@ API Docs
 
 .. automodule:: invenio_mail.ext
    :members:
+
+Tasks
+-----
+.. autotask:: invenio_mail.tasks.send_email

docs/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # This file is part of Invenio.
-# Copyright (C) 2015 CERN.
+# Copyright (C) 2015, 2016 CERN.
 #
 # Invenio is free software; you can redistribute it
 # and/or modify it under the terms of the GNU General Public License as
@@ -44,6 +44,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
+    'celery.contrib.sphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -328,3 +329,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
+
+# Autodoc configuraton.
+autoclass_content = 'both'

invenio_mail/ext.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # This file is part of Invenio.
-# Copyright (C) 2015 CERN.
+# Copyright (C) 2015, 2016 CERN.
 #
 # Invenio is free software; you can redistribute it
 # and/or modify it under the terms of the GNU General Public License as
@@ -49,23 +49,33 @@ def print_email(message, app):
 
 
 class InvenioMail(object):
-    """Invenio-Mail extension.
+    """Invenio-Mail extension."""
 
-    Mails are only printed to the stream if ``MAIL_SUPPRESS_SEND`` is ``True``.
+    def __init__(self, app=None, stream=None):
+        """Extension initialization.
 
-    :param app: Flask application object.
-    :param stream: Stream to print emails to. Defaults to ``sys.stdout``.
-    """
+        Mails are only printed to the stream if ``MAIL_SUPPRESS_SEND`` is
+        ``True``.
 
-    def __init__(self, app=None, stream=None):
-        """Extension initialization."""
+        :param app: Flask application object.
+        :param stream: Stream to print emails to. Defaults to ``sys.stdout``.
+        """
         self.stream = stream or sys.stdout
         self._lock = threading.RLock()
         if app:
             self.init_app(app)
 
     def init_app(self, app):
-        """Flask application initialization."""
+        """Flask application initialization.
+
+        The initialization will:
+
+         * Set default values for the configuration variables.
+         * Initialise the Flask mail extension.
+         * Configure the extension to avoid the email sending in case of debug
+           or ``MAIL_SUPPRESS_SEND`` config variable set. In this case, the
+           email will be written in the stream configured in the extension.
+        """
         self.init_config(app)
         if 'mail' not in app.extensions:
             Mail(app)