README: add general description and documentation

README.txt

@@ -1,5 +1,18 @@
-Configuration
-=============
+=====
+Gadjo
+=====
+
+Gadjo is a base template for Django applications, tailored for
+management interfaces, built to provide a nice and modern look, while
+using progressive enhancement and responsive designs to adapt to
+different environments.
+
+
+Usage
+=====
+
+Make your application base template {% extends "gadjo/base.html" %}.
+
 
 You should add gadjo.finders.XStaticFinder to STATICFILES_FINDERS,
 
@@ -14,13 +27,40 @@ tuples; for example:
   CDNS = [('google', 'https')]
 
 
-Usage
-=====
-
-Make your application base template {% extends "gadjo/base.html" %}.
+Additional static files
+------------------------
 
 Additional static files libraries can be added via INSTALLED_APPS,
 for example 'xstatic.pkg.jquery_tablesorter'; its static files can
 then be referred in a template using the xstatic template tag:
 
   {% xstatic 'jquery_tablesorter' 'jquery.tablesorter.js' %}
+
+
+Progressive enhancement -- Dialogs
+----------------------------------
+
+Links marked with rel="popup" will be opened into dialog boxes.
+
+The dialog title is extracted from "#appbar h2" (this selector can be
+changed with a @data-title-selector attribute on the anchor tag).
+
+The dialog content is extracted from "form" (this selector can be
+changed with a @data-selector attribute).
+
+Buttons (both <button> and <a>) are extracted from the content and
+converted into proper dialog buttons.  A button with "cancel" as its
+class will have its action changed to simply close the dialog, without
+server processing.
+
+After loading the dialog content, a gadjo:dialog-loaded event is
+triggered on the anchor with the dialog content as argument.
+
+Alternatively the server may notice the ajax request and answer with
+an appropriate JSON response. In that case it should have a 'content'
+attribute with the HTML content, or a 'location' attribute in case of
+a redirect.
+
+In case of such a redirect, a gadjo:dialog-done event is triggered on
+the anchor and can be cancelled to prevent the default redirect
+behaviour.

setup.py

@@ -53,7 +53,8 @@ def get_version():
 setup(
     name='gadjo',
     version=get_version(),
-    description='Base templates for management interfaces',
+    description='Django base template tailored for management interfaces',
+    long_description=open(os.path.join(os.path.dirname(__file__), 'README.txt')).read(),
     author='Frederic Peters',
     author_email='fpeters@entrouvert.com',
     packages=find_packages(),