Update documentation + example project

CHANGES.rst

@@ -0,0 +1,14 @@
+Changelog
+=========
+
+Version 0.0.2 (2015-01-14)
+--------------------------
+
+- updated documentation
+- added example project
+- added tests support
+
+Version 0.0.1 (2015-01-14)
+--------------------------
+
+- initial release

README.rst

@@ -24,14 +24,55 @@ This Django Basic Email enable you to create emails in easy way.
 
 This CMS is know to work on Django 1.4+ with Python 2.6+ and 3.3+
 
-Documentation
+Instalation
+===========
+
+Get package or install by pip::
+
+    pip install django-basic-email
+
+
+Configuration
 =============
 
-TBD
+Modify your ``settings.py``. Add ``'basic_email'`` to your
+``INSTALLED_APPS`` like this:
+
+.. code-block:: python
+
+    INSTALLED_APPS = (
+        ...
+        'basic_email',
+    )
+
+Usage
+=====
+
+Create template ``emails/email_example.html`` and send email:
+
+.. code-block:: python
+
+    from basic_email.send import send_email
+    send_email('example', 'joe@doe.com', 'Hello')
+
+Options:
+ - ``template`` template name from scheme ``emails/email_<name>.html``
+ - ``email`` - receiver email
+ - ``subject`` - subject email
+ - ``variables`` - dict with variables to pass to template render
+ - ``fail_silently`` - flag if error in sending email should raise (default ``False``)
+ - ``replace_variables`` - dict with variables to replace in template
+ - ``reply_to`` - reply_to header
+ - ``attachments`` - attachments list (file objects)
+ - ``memory_attachments`` - attachments list (string objects)
 
 
 Testing
 =======
+
+Automated tests
+---------------
+
 Require Tox>=1.8
 
 Testing all platforms
@@ -52,5 +93,30 @@ Example:
 
     tox -e py27-django-17
 
+Testing interface
+-----------------
+
+1. Fork repository (if you don't have write permission).
+2. Create a branch.
+3. Create virtual environment::
+
+    # Preparing virtualenv paths (optional if your profile doesn't have it).
+    export WORKON_HOME=~/Envs
+    source /usr/bin/virtualenvwrapper_lazy.sh
+    # or: source /usr/local/bin/virtualenvwrapper_lazy.sh
+
+    # Start by creating a virtual environment using the helper scripts provided. Do not include the systems site-packages.
+    mkvirtualenv django-basic-email --no-site-packages
+    workon django-basic-email
+
+4. Install ``django-basic-email`` in editable mode::
+
+    pip install -e .
+
+5. Run example project::
 
+    cd example_project && ./manage.py migrate && ./manage.py runserver
 
+6. Add feature or fix a bug.
+7. Push code.
+8. Create a Pull Request.

example_project/.gitignore

@@ -0,0 +1 @@
+.hidden.db

example_project/manage.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python
+import os
+import sys
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")
+    from django.core.management import execute_from_command_line
+    execute_from_command_line(sys.argv)

testproj/settings.py → example_project/settings.py

@@ -1,27 +1,35 @@
 # -*- coding: utf-8 -*-
 import os
 
+abspath = lambda *p: os.path.abspath(os.path.join(*p))
+
 PROJECT_DIR = os.path.dirname(__file__)
+PROJECT_ROOT = abspath(os.path.dirname(__file__))
 
-TEST_PROJ = 'tests'
 SITE_ID = 1
+DEBUG = True
+TEMPLATE_DEBUG = DEBUG
 
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.sqlite3',
-        'NAME': ':memory:',
-    }
+        'NAME': abspath(PROJECT_ROOT, '.hidden.db'),
+        'TEST_NAME': ':memory:',
+    },
 }
 
-SECRET_KEY = 'Fooooo'
+SECRET_KEY = 'CHANGE_THIS_TO_SOMETHING_UNIQUE_AND_SECURE'
 
 MIDDLEWARE_CLASSES = (
+    'django.contrib.sessions.middleware.SessionMiddleware',
     'django.middleware.common.CommonMiddleware',
+    'django.contrib.auth.middleware.AuthenticationMiddleware',
+    'django.contrib.messages.middleware.MessageMiddleware',
 )
 
 TEST_RUNNER = 'django.test.simple.DjangoTestSuiteRunner'
 
-ROOT_URLCONF = TEST_PROJ + '.urls'
+ROOT_URLCONF = 'urls'
 
 TEMPLATE_DIRS = (
     os.path.join(PROJECT_DIR, 'templates'),
@@ -33,9 +41,14 @@
     'django.contrib.sessions',
     'django.contrib.admin',
     'django.contrib.sites',
+    'django.contrib.staticfiles',
     'basic_email',
+    'tests',
 )
 
+
+STATIC_URL = '/static/'
+
 COVERAGE_EXCLUDE_MODULES = (
     "basic_email.migrations.*",
     "basic_email.tests*",

test_runner.py → example_project/test_runner.py

@@ -6,13 +6,13 @@
 except ImportError:
     coverage = None
 
-os.environ['DJANGO_SETTINGS_MODULE'] = 'testproj.settings'
+os.environ['DJANGO_SETTINGS_MODULE'] = 'example_project.settings'
 current_dirname = os.path.dirname(__file__)
 sys.path.insert(0, current_dirname)
 sys.path.insert(0, os.path.join(current_dirname, '..'))
 
 
-from testproj import settings
+from example_project import settings
 
 
 def run_tests(settings):
@@ -24,7 +24,7 @@ def run_tests(settings):
 
     TestRunner = get_runner(settings)
     test_runner = TestRunner(interactive=False)
-    failures = test_runner.run_tests(['basic_email'])
+    failures = test_runner.run_tests(['tests'])
     return failures
 
 

example_project/urls.py

@@ -0,0 +1,9 @@
+from django.conf.urls import include, patterns
+from django.contrib import admin
+
+admin.autodiscover()
+
+urlpatterns = patterns(
+    '',
+    (r'^admin/', include(admin.site.urls)),
+)

setup.py

@@ -38,7 +38,7 @@ def local_open(fname):
 
 setup(
     name=package_name,
-    test_suite='test_runner.main',
+    test_suite='example_project.test_runner.main',
     version=basic_email.__version__,
     description=basic_email.__doc__,
     author=basic_email.__author__,