Improved STRtree docs (#623)

* docstring for strtree query method

* note about immutability, slight reformatting

not sure if immutable is the correct term, might be misleading?

* let's call it a spatial index

* rewording strtree docstring

* reworded strtree doc

* explicitely mention "extents"!
* rewrote subsequent filtering part, I hope it became better, not worse
* Rename R-Tree to STRTree to avoid confusion with rtree module trees
* name-drop "spatial index"

* strtree doc: add example on testing for intersection

+use query_geom variable name to help readability

* strtree doc: note about monkey patching for extra attributes

added code inside a note, untested if this comes out correctly. also no clue if the links work. rst is weird.

Co-authored-by: Sean Gillies <sean.gillies@gmail.com>

docs/manual.rst

@@ -2745,4 +2745,4 @@ References
 .. _frozenset: https://docs.python.org/library/stdtypes.html#frozenset
 .. _Sorting HowTo: https://wiki.python.org/moin/HowTo/Sorting/
 .. _Python geo interface: https://gist.github.com/2217756
-.. _polylabel: https://github.com/mapbox/polylabel
+.. _polylabel: https://github.com/mapbox/polylabel

shapely/strtree.py

@@ -3,10 +3,12 @@
 
 class STRtree:
     """
-    STRtree is an R-tree that is created using the Sort-Tile-Recursive
-    algorithm. STRtree takes a sequence of geometry objects as initialization
-    parameter. After initialization the query method can be used to make a
-    spatial query over those objects.
+    STRtree is an R-tree spatial index that is created using the
+    Sort-Tile-Recursive algorithm.
+    
+    STRtree takes a sequence of geometry objects as initialization
+    parameter. Once created, it is immutable. The query method can
+    be used to make spatial queries over the objects on the index.
 
     >>> from shapely.geometry import Polygon
     >>> polys = [ Polygon(((0, 0), (1, 0), (1, 1))), Polygon(((0, 1), (0, 0), (1, 0))), Polygon(((100, 100), (101, 100), (101, 101))) ]
@@ -48,6 +50,9 @@ def __del__(self):
             self._tree_handle = None
 
     def query(self, geom):
+        """Returns a list of objects on the index whose extents
+        intersect the given geometry's extents.
+        """
         if self._n_geoms == 0:
             return []