Merge 74cab0d into 38a9021

docs/geometry.rst

@@ -173,3 +173,17 @@ specified, rounding precision will be disabled showing full precision.
 Format types ``'x'`` and ``'X'`` show a hex-encoded string representation of
 WKB or Well-Known Binary, with the case of the output matched the
 case of the format type character.
+
+.. _canonical-form:
+
+Canonical form
+--------------
+When geometries are constructed, they are created according to some conventions:
+
+* the coordinates of exterior rings follow a clockwise orientation, interior rings
+  have a counter-clockwise orientation. This is the opposite of the OGC specifications
+  because the choise was made before this was included in the standard.
+* the starting point of rings is lower left.
+* collections are ordered by geometry type.
+
+It is important to note that input geometries do not have to follow these conventions.

shapely/_geometry.py

@@ -731,14 +731,15 @@ def set_precision(geometry, grid_size, mode="valid_output", **kwargs):
     collapse to empty geometries if all vertices are closer together than
     grid_size. Z values, if present, will not be modified.
 
-    Note: subsequent operations will always be performed in the precision of
-    the geometry with higher precision (smaller "grid_size"). That same
-    precision will be attached to the operation outputs.
-
-    Also note: input geometries should be geometrically valid; unexpected
-    results may occur if input geometries are not.
-
-    Returns None if geometry is None.
+    Notes:
+
+    * subsequent operations will always be performed in the precision of
+      the geometry with higher precision (smaller "grid_size"). That same
+      precision will be attached to the operation outputs.
+    * input geometries should be geometrically valid; unexpected results may
+      occur if input geometries are not.
+    * the geometry returned will be in :ref:`canonical form <canonical-form>`.
+    * returns None if geometry is None.
 
     Parameters
     ----------

shapely/constructive.py

@@ -533,9 +533,9 @@ def make_valid(geometry, **kwargs):
 def normalize(geometry, **kwargs):
     """Converts Geometry to normal form (or canonical form).
 
-    This method orders the coordinates, rings of a polygon and parts of
-    multi geometries consistently. Typically useful for testing purposes
-    (for example in combination with ``equals_exact``).
+    In :ref:`canonical form <canonical-form>`, the coordinates, rings of a polygon and
+    parts of multi geometries are ordered consistently. Typically useful for testing
+    purposes (for example in combination with ``equals_exact``).
 
     Parameters
     ----------