improved how to

README.md

@@ -5,29 +5,39 @@ A static gallery generator plugin for Pelican, based on the Sigal
 Colorbox/Galleria static site generator.
 
 ##How To
-1. Put this folder into your Pelican plugins directory. Add 'siglican' to
-   PLUGINS in pelicanconf.py.
-2. Create a 'siglican' directory in your base directory, at the same level as
-   'content'. Drag 'colorbox' or 'galleria' from the 'themes' directory into
-   this folder. Also create an 'images' subdirectory under 'siglican'.
-3. Create album and image metadata, as desired.
-4. Create theme directory inside of 'siglican'. Use the colorbox or galleria
-   theme as a starting point. Make sure that your Pelican theme's base.html
-   template has a 'head' block defined before </head>.
+1. Add this package to your Pelican plugins directory.
+2. Add 'siglican' to PLUGINS in pelicanconf.py. Add SIGLICAN_ settings to
+   pelicanconf.py as desired.
+3. Create a *siglican* directory in your base directory, at the same level as
+   *content*.
+4. Drag gallery.md from examples to your pelican *pages* directory and edit it.
+   This gives Pelican a hook into your root gallery.
+5. Drag siglican_gallery.html into your Pelican theme's *templates* directory.
+   This is the template for your root gallery.
+6. Copy one of the example themes to *siglican*. This dictates how album pages
+   look. Modify to your heart's content.
+7. Make sure your Pelican theme's base.html template has a 'head' block
+   (e.g., **{% block head %}{% endblock %}**) defined before **</head>**. That
+   will give your siglican theme a way to inject gallery-specific css and js
+   into your gallery pages. 
+8. Create an 'images' folder under 'siglican'. Add album folders along with
+   images and metadata.
 
-###Example directory tree:
+###Example directory excerpt:
 ```
    /site
-     /content/*
-     /plugins/siglican/*.py
-     /siglican
-       /images
-         /album1
-         /album2
-         /...
-       /[colorbox|galleria]
-         /static/*
-         /templates/album.html
+      /content/
+         /pages/gallery.md
+      /plugins/siglican/*.py
+      /siglican
+         /images
+            /album1
+            /album2
+            /...
+         /[colorbox|galleria]
+            /static/*
+            /templates/album.html
+      /themes/theme/templates/siglican_gallery.html
 ```
 
 ###Pelican Configuration Settings

album.py

@@ -37,8 +37,6 @@ from collections import defaultdict
 from .compat import strxfrm, UnicodeMixin, url_quote
 from .utils import read_markdown, url_from_path
 
-# TODO ** move logger out to here
-
 class Media(UnicodeMixin):
     """Base Class for media files.
 

compat.py

@@ -20,8 +20,8 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-## ** TODO: consider switching to use pelican's compat features in utils.py
-##          (which uses Django calls)
+## ** github1O: phase out this file and use pelican's compat features in 
+##              in utils.py (which uses Django calls)
 
 import locale
 import sys

pkgmeta.py

@@ -22,7 +22,7 @@
 
 __title__ = 'siglican'
 __author__ = 'Scott Boone'
-__version__ = '0.0.1-alpha'
+__version__ = '0.0.2-beta'
 __license__ = 'MIT'
 __url__ = 'https://github.com/sawall/siglican'
 __all__ = ['__title__', '__author__', '__version__', '__license__', '__url__']

siglican.py

@@ -184,8 +184,8 @@ class SigalGalleryGenerator(Generator):
         logger.debug('siglican: albums:\n%r', self.albums.values())
         
         # update the jinja context so that templates can access it:
-        self._update_context(('albums', )) # ** not 100% certain this is needed
-        self.context['ALBUMS'] = self.albums
+        #self._update_context(('albums', ))   # unnecessary? **
+        self.context['ALBUMS'] = self.albums  # ** change to SIGLICAN_ALBUMS?
         
         # update the jinja context with the default sigal settings:
         for k,v in _DEFAULT_SIGLICAN_SETTINGS.iteritems():
@@ -196,8 +196,11 @@ class SigalGalleryGenerator(Generator):
         """ Creates gallery destination directories, thumbnails, resized
             images, and moves everything into the destination."""
         
-        # note: ignore the writer because it might be from another plugin
-        # see https://github.com/getpelican/pelican/issues/1459
+        # note: ignore the writer sent by Pelican because it's not certain
+        # which Writer it will send. if another active plugin also implements
+        # Writer, Pelican may send that instead of one of its core Writers.
+        # I logged a feature request here:
+        # https://github.com/getpelican/pelican/issues/1459
         
         # create destination directory
         if not os.path.isdir(self.settings['SIGLICAN_DESTINATION']):
@@ -245,22 +248,13 @@ class SigalGalleryGenerator(Generator):
         
             logger.info("siglican theme: %s", self.theme)
             
-            # note 2: when Pelican calls generate_output() on a Generator plugin,
-            # it's uncertain which Writer will be sent; if other plugins with
-            # Writers are loaded, it might be one of those Writers instead of 
-            # one of the core Pelican writers. thus this plugin explicitly calls
-            # a Writer so that it doesn't get any nasty surprises due to plugin
-            # conflicts. I logged a feature request to Pelican here:
-            # https://github.com/getpelican/pelican/issues/1459
-            
             self.writer = Writer(self.context, self.theme, 'album')
             for album in self.albums.values():
                 self.writer.write(album)
             
             ## possible cleanup:
-            ##   - missing some writer options that Sigal had, bring back?
-            ##   - make sure all necessary template info is accessible by the writer
-            ##   - make sure thumbnails don't break in some cases
+            ##   - bring back Writer options that Sigal had?
+            ##   - make sure thumbnails don't break in some cases [fixed?]
 
 def get_generators(generators):
     return SigalGalleryGenerator

writer.py

@@ -61,10 +61,9 @@ class Writer(object):
             pass
 
         # note: it's impossible to add templates to an existing jinja env,
-        # which is why we create a custom environment here that includes
-        # templates from both the Pelican theme and the siglican theme.
-        # it's also ok for the "album.html" template to live in the Pelican
-        # theme.
+        # so we create a custom environment here that includes templates from
+        # both the Pelican theme and the siglican theme. it's also ok for the
+        # "album.html" template to live in the Pelican theme.
         
         # instantiate environment with pelican and siglican templates
         theme_paths = [ os.path.join(self.theme, 'templates'),