Make the gallery directive less of a hack

v7/gallery_directive/README.md

@@ -5,4 +5,44 @@ Usage::
     .. gallery:: demo
 
 This should embed the gallery found in galleries/demo in your post.
-Keep in mind that this is a horrible, horrible hack.
+Keep in mind that this is sort of a hack.
+
+Caveats:
+
+* The styling of the displayed gallery is meant to sort-of-work
+with the bootstrap-based themes
+
+* It will **not** have the fancy rows/columns layout of the regular
+gallery in bootstrap, either.
+
+* It will look bad in most other themes. But you can customize it by
+creating your own gallery_fancy.tmpl. Here's the one that comes with
+ the plugin for inspiration:
+
+```html
+## -*- coding: utf-8 -*-
+
+%if post:
+<p>
+    ${post.text()}
+</p>
+%endif
+
+<div id="gallery_container"></div>
+%if photo_array:
+<div class="row">
+  %for image in photo_array:
+    <div class="col-xs-6 col-md-3">
+        <a href="${image['url']}" class="thumbnail image-reference" title="${image['title']|h}">
+            <img src="${image['url_thumb']}" alt="${image['title']|h}" />
+        </a>
+    </div>
+  %endfor
+</div>
+
+<ul class="thumbnails">
+        <li>
+</ul>
+%endif
+```
+

v7/gallery_directive/gallery_directive.py

@@ -91,10 +91,8 @@ def run(self):
         context.update(self.site.GLOBAL_CONTEXT)
         context.update(kw)
         output = self.site.template_system.render_template(
-            'gallery.tmpl',
+            'gallery_fancy.tmpl',
             None,
             context
         )
-        # This magical comment makes everything work. Try removing it!
-        output = '\n<!-- foo -->\n%s\n\n\n' % output
         return [nodes.raw('', output, format='html')]