improve docstrings

sigal/gallery.py

@@ -48,7 +48,7 @@ class Gallery:
         self.writer = Writer(settings, output_dir)
 
     def build_paths(self):
-        "get the list of directories with images"
+        "Build the list of directories with images"
 
         self.paths = {}
 
@@ -74,9 +74,6 @@ class Gallery:
                     alb_thumb = self.find_representative(relpath)
                     self.paths[relpath]['representative'] = alb_thumb
 
-        # import json
-        # print json.dumps(self.paths, indent=4)
-
     def find_representative(self, path):
         "Find the representative image for a given path"
 
@@ -90,7 +87,7 @@ class Gallery:
         return self.paths[path]['img'][0]
 
     def build(self):
-        "Create image gallery"
+        "Create the image gallery"
 
         self.logger.info("Generate gallery in %s ...", self.output_dir)
         self.build_paths()
@@ -125,7 +122,6 @@ class Gallery:
         # loop on images
         for f in progress.bar(imglist):
             filename = os.path.split(f)[1]
-
             im_name = os.path.join(img_out, filename)
 
             if os.path.isfile(im_name) and not self.force:

sigal/image.py

@@ -35,7 +35,13 @@ from PIL import ImageDraw, ImageOps
 
 
 class Image:
-    "Handle Images: resize, thumbnail, ..."
+    """ Image container
+
+    resize, thumbnail, ...
+
+    :param filename: path to an image
+
+    """
 
     def __init__(self, filename):
         self.filename = filename
@@ -46,11 +52,14 @@ class Image:
         self.img.save(filename, quality=quality)
 
     def resize(self, size):
-        """Resize the image
+        """ Resize the image
 
         - check if the image format is portrait or landscape and adjust `size`.
         - compute the width and height ratio, and keep the min to resize the
           image inside the `size` box without distorting it.
+
+        :param size: tuple with the (with, height) to resize
+
         """
 
         if self.img.size[0] > self.img.size[1]:
@@ -68,7 +77,7 @@ class Image:
             self.img = self.img.resize(newsize, PILImage.ANTIALIAS)
 
     def add_copyright(self, text):
-        "add copyright to image"
+        "Add a copyright to the image"
 
         draw = ImageDraw.Draw(self.img)
         draw.text((5, self.img.size[1] - 15), '\xa9 ' + text)
@@ -85,7 +94,7 @@ class Image:
 
 
 def copy_exif(srcfile, dstfile):
-    "copy the exif metadatas from src to dest images"
+    "Copy the exif metadatas from src to dest images"
 
     logger = logging.getLogger(__name__)
 

sigal/writer.py

@@ -44,7 +44,7 @@ THEMES_PATH = os.path.normpath(os.path.join(
 
 
 def do_link(link, title):
-    "return html link"
+    "Return a html link"
     return '<a href="%s">%s</a>' % (link, title)
 
 
@@ -77,7 +77,7 @@ class Writer():
         }
 
     def copy_assets(self):
-        "copy the theme files in the output dir"
+        "Copy the theme files in the output dir"
 
         self.theme_path = os.path.join(self.output_dir, 'theme')
         copy_tree(self.theme, self.theme_path)