Improve OCitySMap's API and documentation

Signed-off-by: Maxime Petazzoni <maxime.petazzoni@bulix.org>

ocitysmap2/__init__.py

@@ -24,7 +24,52 @@
 
 """OCitySMap 2.
 
-TODO: write some documentation here
+OCitySMap is a Mapnik-based map rendering engine from OpenStreetMap.org data.
+It is architectured around the concept of Renderers, in charge of rendering the
+map and all the visual features that go along with it (scale, grid, legend,
+index, etc.) on the given paper size using a provided Mapnik stylesheet,
+according to their implemented layout.
+
+The PlainRenderer for example renders a full-page map with its grid, a title
+header and copyright notice, but without the index.
+
+How to use OCitySMap?
+---------------------
+
+The API of OCitySMap is very simple. First, you need to instanciate the main
+OCitySMap class with the path to your OCitySMap configuration file (see
+ocitysmap.conf-template):
+
+
+    ocitysmap = ocitysmap2.OCitySMap('/path/to/your/config')
+
+The next step is to create a RenderingConfiguration, the object that
+encapsulates all the information to parametize the rendering, including the
+Mapnik stylesheet. You can retrieve the list of supported stylesheets (directly
+as Stylesheet objects) with:
+
+    styles = ocitysmap.get_all_style_configurations()
+
+Fill in your RenderingConfiguration with the map title, the OSM ID or bounding
+box, the chosen map language, the Stylesheet object and the paper size (in
+millimeters) and simply pass it to OCitySMap's render method:
+
+    ocitysmap.render(rendering_configuration, layout_name,
+                     output_formats, prefix)
+
+The layout name is the renderer's key name. You can get the list of all
+supported renderers with ocitysmap.get_all_renderers(). The output_formats is a
+list of output formats. For now, the following formats are supported:
+
+    * PNG at 300dpi
+    * PDF
+    * SVG
+    * SVGZ (gzipped-SVG)
+    * PS
+
+The prefix is the filename prefix for all the rendered files. This is usually a
+path to the destination's directory, eventually followed by some unique, yet
+common prefix for the files rendered for a job.
 """
 
 __author__ = 'The MapOSMatic developers'
@@ -127,7 +172,8 @@ class Stylesheet:
 
 class OCitySMap:
     """
-    TODO: documentation here
+    This is the main entry point of the OCitySMap map rendering engine. Read
+    this module's documentation for more details on its API.
     """
 
     DEFAULT_REQUEST_TIMEOUT_MIN = 15
@@ -286,9 +332,12 @@ class OCitySMap:
         raise LookupError, 'The requested stylesheet %s was not found!' % name
 
     def get_all_renderers(self):
-        """Returns the list of all available layout renderers (list of Renderer
-        objects)."""
-        pass
+        """Returns the list of all available layout renderers (list of
+        Renderer classes)."""
+        return renderers.get_renderers()
+
+    def get_all_paper_sizes(self):
+        return renderers.get_paper_sizes()
 
     def render(self, config, renderer_name, output_formats, file_prefix):
         """Renders a job with the given rendering configuration, using the

ocitysmap2/map_canvas.py

@@ -53,7 +53,10 @@ class MapCanvas:
 
         self._proj = mapnik.Projection(_MAIN_PROJECTION)
 
-        # TODO: document!
+        # This is where the magic of the map canvas happens. Given an original
+        # bounding box and a graphical ratio for the output, the bounding box
+        # is adjusted (extended) to fill the destination zone. See
+        # _fix_bbox_ratio for more details on how this is done.
         orig_envelope = self._project_envelope(bounding_box)
 
         off_x, off_y, width, height = self._fix_bbox_ratio(
@@ -83,6 +86,9 @@ class MapCanvas:
         l.info('MapCanvas rendering map on %dx%dpx.' % (g_width, g_height))
 
     def _fix_bbox_ratio(self, off_x, off_y, width, height, dest_ratio):
+        """Adjusts the area expressed by its origin's offset and its size to
+        the given destination ratio by tweaking one of the two dimensions
+        depending on the current ratio and the destination ratio."""
         cur_ratio = float(width)/height
 
         if cur_ratio < dest_ratio:
@@ -100,7 +106,13 @@ class MapCanvas:
                        line_width=1.0):
         """
         Args:
-            shape_file (shapes.ShapeFile): ...
+            shape_file (shapes.ShapeFile): path to the shape file to overlay on
+                this map canvas.
+            str_color (string): litteral name of the layer's color, needs to be
+                understood by mapnik.Color.
+            alpha (float): transparency factor in the range 0 (invisible) -> 1
+                (opaque).
+            line_width (float): line width for the features that will be drawn.
         """
         col = mapnik.Color(str_color)
         col.a = int(255 * alpha)
@@ -109,11 +121,10 @@ class MapCanvas:
                              'line_width': line_width})
         l.debug('Added shape file %s to map canvas as layer %s.' %
                 (shape_file.get_filepath(), shape_file.get_layer_name()))
-        return shape_file
 
     def render(self):
-        """Render the map in memory with all the added shapes. Returns the
-        corresponding mapnik.Map object."""
+        """Render the map in memory with all the added shapes. The Mapnik Map
+        object can be accessed with self.get_rendered_map()."""
 
         # Add all shapes to the map
         for shape in self._shapes:

ocitysmap2/renderers.py

@@ -482,6 +482,12 @@ def get_renderers():
     """Returns the list of available renderers' names."""
     return _RENDERERS
 
+def get_paper_sizes():
+    """Returns a list of paper sizes specifications, 3-uples (name, width in
+    millimeters, height in millimeters). The paper sizes are returned assuming
+    portrait mode."""
+    return Renderer.PAPER_SIZES
+
 if __name__ == '__main__':
     import coords
     import cairo