merged documentation

docs/Makefile

@@ -43,6 +43,7 @@ clean:
 
 readme:
 	which pandoc &> /dev/null && pandoc ../README.md -o ../README.rst
+	which pandoc &> /dev/null && pandoc ../mailjet/contrib/django_mailjet/README.md -o ../mailjet/contrib/django_mailjet/README.rst
 
 html: readme
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/conf.py

@@ -14,6 +14,9 @@
 import sys, os
 os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings'
 
+from django.conf import settings
+settings.configure()
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.

docs/django.rst

@@ -0,0 +1,2 @@
+.. include:: ../mailjet/contrib/django_mailjet/README.rst
+

docs/index.rst

@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 4
 
    usage
+   django
    mailjet
 
 Indices and tables

docs/mailjet.rst

@@ -56,4 +56,3 @@ Subpackages
 
     mailjet.contrib.django_mailjet
 
-

mailjet/contrib/django_mailjet/README.md

@@ -1,3 +1,6 @@
+Django integration
+------------------
+
 Introduction
 ============
 
@@ -13,11 +16,11 @@ Installation
 
 In `settings.py`:
 
-    - set `MAILJET_LIST_NAME` and `MAILJET_LIST_LABEL`, note that
-      it may not contain non-alphanumeric characters, those are used as
-      defaults for `mailjet.contrib.django_mailjet.forms.SubscriptionForm`,
-    - add to `INSTALLED_APPS`: `mailjet.contrib.django_mailjet`
-      for templates to be loadable.
+- set `MAILJET_LIST_NAME` and `MAILJET_LIST_LABEL`, note that
+  it may not contain non-alphanumeric characters, those are used as
+  defaults for `mailjet.contrib.django_mailjet.forms.SubscriptionForm`,
+- add to `INSTALLED_APPS`: `mailjet.contrib.django_mailjet`
+  for templates to be loadable.
 
 Include `mailjet.contrib.django_mailjet.urls` in `urls.py`, ie.:
 

mailjet/contrib/django_mailjet/forms.py

@@ -6,15 +6,22 @@
 
 
 class SubscriptionForm(forms.Form):
+    """ Simple subscription form """
     email = forms.EmailField()
 
     def __init__(self, list_name=None, list_label=None, *args, **kwargs):
+        """
+        If `list_name` and `list_label` are None, then
+        `settings.MAILJET_LIST_NAME` and `settings.MAILJET_LIST_LABEL` will be
+        used.
+        """
         self.list_name = list_name or settings.MAILJET_LIST_NAME
         self.list_label = list_label or settings.MAILJET_LIST_LABEL
 
         super(SubscriptionForm, self).__init__(*args, **kwargs)
 
     def clean_email(self):
+        """ Raise ValidationError if the contact exists. """
         contacts = self.api.lists.contacts(id=self.list_id)['result']
 
         for contact in contacts:
@@ -25,23 +32,28 @@ def clean_email(self):
         return self.cleaned_data['email']
 
     def save(self):
+        """ Call `add_contact()` """
         self.add_contact()
 
     def add_contact(self):
+        """ Create a contact with using the email on the list. """
         self.api.lists.addcontact(contact=self.cleaned_data['email'],
                 id=self.list_id, method='POST')
 
     @property
     def api(self):
+        """ Get or create an Api() instance using django settings. """
         api = getattr(self, '_api', None)
 
         if api is None:
             self._api = mailjet.Api()
 
         return self._api
 
+
     @property
     def list_id(self):
+        """ Get or create the list id. """
         list_id = getattr(self, '_list_id', None)
 
         if list_id is None:

mailjet/contrib/django_mailjet/templates/newsletter/subscription.html → mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_form.html

@@ -1,11 +1,10 @@
-{% extends 'newsletter/base.html' %}
+{% extends 'django_mailjet/base.html' %}
 
 {% load i18n %}
 
 {% block body %}
 <form method="post" action="">
-    {{ form.email.errors }}
-    {{ form.email }}
+    {{ form.as_p }}
     {% csrf_token %}
     <input type="submit" value="{% trans 'Submit' %}" />
 </form>

mailjet/contrib/django_mailjet/templates/newsletter/subscription_success.html → mailjet/contrib/django_mailjet/templates/django_mailjet/subscription_success.html

@@ -1,4 +1,4 @@
-{% extends 'newsletter/base.html' %}
+{% extends 'django_mailjet/base.html' %}
 
 {% load i18n %}
 

mailjet/contrib/django_mailjet/urls.py

@@ -1,12 +1,22 @@
+"""
+Defines basic urls.
+
+django_mailjet_subscription_form
+    Url to the basic form view: SubscriptionView.
+
+django_mailjet_subscription_success
+    Url to the basic success template.
+"""
+
 from django.conf.urls import patterns, url
 from django.views import generic
 
 import views
 
 urlpatterns = patterns('newsletter.views',
     url(r'subscription/$', views.SubscriptionView.as_view(),
-        name='newsletter_subscription'),
+        name='django_mailjet_subscription_form'),
     url(r'subscription/success/$', generic.TemplateView.as_view(
-        template_name='newsletter/subscription_success.html'),
-        name='newsletter_subscription_success'),
+        template_name='django_mailjet/subscription_success.html'),
+        name='django_mailjet_subscription_success'),
 )

mailjet/contrib/django_mailjet/views.py

@@ -7,10 +7,12 @@
 
 
 class SubscriptionView(generic.FormView):
+    """ Basic subscription views """
     form_class = SubscriptionForm
-    template_name = 'newsletter/subscription.html'
-    success_url = reverse_lazy('newsletter_subscription_success')
+    template_name = 'django_mailjet/subscription_form.html'
+    success_url = reverse_lazy('django_mailjet_subscription_success')
 
     def form_valid(self, form):
+        """ Call `form.save()` and super itself. """
         form.save()
         return super(SubscriptionView, self).form_valid(form)