DOC: Update docs, add multithreading section (#169)

pygeos · Jul 23, 2020 · 631bfdb · 631bfdb
1 parent 01fbbe3
commit 631bfdb
Show file tree

Hide file tree

Showing 13 changed files with 120 additions and 144 deletions.
diff --git a/README.rst b/README.rst
@@ -35,26 +35,35 @@ Note: PyGEOS is a very young package. While the available functionality should
 be stable and working correctly, it's still possible that APIs change in upcoming
 releases. But we would love for you to try it out, give feedback or contribute!
 
-Why ufuncs?
------------
+What is a ufunc?
+----------------
 
 A universal function (or ufunc for short) is a function that operates on
 n-dimensional arrays in an element-by-element fashion, supporting array
 broadcasting. The for-loops that are involved are fully implemented in C
 diminishing the overhead of the Python interpreter.
 
+Multithreading
+--------------
+
+PyGEOS functions support multithreading. More specifically, the Global
+Interpreter Lock (GIL) is released during function execution. Normally in Python, the
+GIL prevents multiple threads from computing at the same time. PyGEOS functions
+internally releases this constraint so that the heavy lifting done by GEOS can be
+done in parallel, from a single Python process.
 
 The Geometry object
 -------------------
 
 The `pygeos.Geometry` object is a container of the actual GEOSGeometry object.
-A C pointer to this object is stored in a static attribute of the `Geometry`
-object. This keeps the python interpreter out of the ufunc inner loop. The
-Geometry object keeps track of the underlying GEOSGeometry and
+The Geometry object keeps track of the underlying GEOSGeometry and
 allows the python garbage collector to free memory when it is not
 used anymore.
 
-`Geometry` objects are immutable. Construct them as follows:
+`Geometry` objects are immutable. This means that after constructed, they cannot
+be changed inplace. Every PyGEOS operation will result in a new object being returned.
+
+Construct a Geometry from a WKT (Well-Known Text):
 
 .. code:: python
 
@@ -68,7 +77,7 @@ Or using one of the provided (vectorized) functions:
 
   >>> from pygeos import points
 
-  >>> point = points(5.2, 52.1)
+  >>> point = points([(5.2, 52.1), (5.1, 52.2)]]
 
 Examples
 --------
@@ -107,76 +116,6 @@ Compute the area of all possible intersections of two lists of polygons:
 
 See the documentation for more: https://pygeos.readthedocs.io
 
-Installation using conda
-------------------------
-
-Pygeos requires the presence of NumPy and GEOS >= 3.5. It is recommended to install
-these using Anaconda from the conda-forge channel (which provides pre-compiled
-binaries)::
-
-    $ conda install numpy geos pygeos --channel conda-forge
-
-Installation using system GEOS
-------------------------------
-
-On Linux::
-
-    $ sudo apt install libgeos-dev
-
-On OSX::
-
-    $ brew install geos
-
-Make sure `geos-config` is available from you shell; append PATH if necessary::
-
-    $ export PATH=$PATH:/path/to/dir/having/geos-config
-    $ pip install pygeos
-
-
-Installation for developers
----------------------------
-
-Ensure you have numpy and GEOS installed (either using conda or using system
-GEOS, see above).
-
-Clone the package::
-
-    $ git clone https://github.com/pygeos/pygeos.git
-
-Install it using `pip`::
-
-    $ pip install -e .[test]
-
-Run the unittests::
-
-    $ pytest
-
-If GEOS is installed, normally the ``geos-config`` command line utility
-will be available, and ``pip install`` will find GEOS automatically.
-But if needed, you can specify where PyGEOS should look for the GEOS library
-before installing it:
-
-On Linux / OSX::
-
-    $ export GEOS_INCLUDE_PATH=$CONDA_PREFIX/Library/include
-    $ export GEOS_LIBRARY_PATH=$CONDA_PREFIX/Library/lib
-
-On windows (assuming you are in a Visual C++ shell)::
-
-    $ set GEOS_INCLUDE_PATH=%CONDA_PREFIX%\Library\include
-    $ set GEOS_LIBRARY_PATH=%CONDA_PREFIX%\Library\lib
-
-
-Memleak testing using valgrind for developers
----------------------------------------------
-
-PyGEOS uses pytest-valgrind to automatically detect memory leaks. As tests take
-about 20 minutes to complete, this is not done as part of the CI. Run the tests
-locally using the included dockerfile::
-
-    $ docker build . -f ./docker/Dockerfile.valgrind -t pygeos/valgrind
-    $ docker run pygeos/valgrind:latest valgrind --show-leak-kinds=definite --log-file=/tmp/valgrind-output python -m pytest -vv --valgrind --valgrind-log=/tmp/valgrind-output > valgrind.log
-
 
 Relationship to Shapely
 -----------------------

diff --git a/docs/constructive.rst b/docs/constructive.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.constructive`
-==========================
+Constructive operations
+=======================
 
 .. automodule:: pygeos.constructive
    :members:

diff --git a/docs/coordinates.rst b/docs/coordinates.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.coordinates`
-=========================
+Coordinate operations
+=====================
 
 .. automodule:: pygeos.coordinates
    :members:

diff --git a/docs/creation.rst b/docs/creation.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.creation`
-======================
+Geometry creation
+=================
 
 .. automodule:: pygeos.creation
    :members:

diff --git a/docs/geometry.rst b/docs/geometry.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.geometry`
-======================
+Geometry properties
+===================
 
 .. automodule:: pygeos.geometry
    :members:

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,66 +3,25 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to the PyGEOS documentation
-===================================
-
-PyGEOS is a C/Python library with vectorized geometry functions. The geometry
-operations are done in the open-source geometry library GEOS. PyGEOS wraps
-these operations in NumPy ufuncs providing a performance improvement when
-operating on arrays of geometries.
-
-Why ufuncs?
------------
-
-A universal function (or ufunc for short) is a function that operates on
-n-dimensional arrays in an element-by-element fashion, supporting array
-broadcasting. The for-loops that are involved are fully implemented in C
-diminishing the overhead of the Python interpreter.
-
-
-The Geometry object
--------------------
-
-The `pygeos.Geometry` object is a container of the actual GEOSGeometry object.
-A C pointer to this object is stored in a static attribute of the `Geometry`
-object. This keeps the python interpreter out of the ufunc inner loop. The
-Geometry object keeps track of the underlying GEOSGeometry and
-allows the python garbage collector to free memory when it is not
-used anymore.
-
-`Geometry` objects are immutable. Construct them as follows:
-
-.. code:: python
-
-  >>> from pygeos import Geometry
-
-  >>> geometry = Geometry("POINT (5.2 52.1)")
-
-Or using one of the provided (vectorized) functions:
-
-.. code:: python
-
-  >>> from pygeos import points
-
-  >>> point = points(5.2, 52.1)
-
+.. include:: ../README.rst
 
 API Reference
 =============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
+   installation
+   io
    creation
-   constructive
-   coordinates
    geometry
-   io
-   linear
    measurement
+   coordinates
    predicates
    set_operations
+   constructive
+   linear
    strtree
    changelog
 

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -0,0 +1,78 @@
+Installation
+============
+
+Installation from PyPI
+----------------------
+
+PyGEOS is available as a binary distribution (wheel) for Linux, OSX and Windows platforms.
+Install as follows::
+
+    $ pip install pygeos
+
+
+Installation using conda
+------------------------
+
+PyGEOS is available on the conda-forage channel. Install as follows::
+
+    $ conda install pygeos --channel conda-forge
+
+
+Installation with custom GEOS libary
+------------------------------------
+
+On Linux::
+
+    $ sudo apt install libgeos-dev
+
+On OSX::
+
+    $ brew install geos
+
+Make sure `geos-config` is available from you shell; append PATH if necessary::
+
+    $ export PATH=$PATH:/path/to/dir/having/geos-config
+    $ pip install pygeos --no-binary
+
+We do not have a recipe for Windows platforms. The following steps should enable you
+to build PyGEOS yourself:
+
+- Get a C compiler applicable to your Python version (https://wiki.python.org/moin/WindowsCompilers)
+- Download and install a GEOS binary (https://trac.osgeo.org/osgeo4w/)
+- Set GEOS_INCLUDE_PATH and GEOS_LIBRARY_PATH environment variables
+- Run ``pip install pygeos --no-binary``
+
+Installation from source
+------------------------
+
+The same as above, but then instead of installing pygeos with pip, you clone the
+package from Github::
+
+    $ git clone git@github.com:pygeos/pygeos.git
+
+Install it in development mode using `pip`::
+
+    $ pip install -e .[test]
+
+Run the unittests::
+
+    $ pytest pygeos
+
+
+Notes on GEOS discovery
+-----------------------
+
+If GEOS is installed, normally the ``geos-config`` command line utility
+will be available, and ``pip install`` will find GEOS automatically.
+But if needed, you can specify where PyGEOS should look for the GEOS library
+before installing it:
+
+On Linux / OSX::
+
+    $ export GEOS_INCLUDE_PATH=$CONDA_PREFIX/Library/include
+    $ export GEOS_LIBRARY_PATH=$CONDA_PREFIX/Library/lib
+
+On Windows (assuming you are in a Visual C++ shell)::
+
+    $ set GEOS_INCLUDE_PATH=%CONDA_PREFIX%\Library\include
+    $ set GEOS_LIBRARY_PATH=%CONDA_PREFIX%\Library\lib
diff --git a/docs/io.rst b/docs/io.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.io`
-================
+Input/Output
+============
 
 .. automodule:: pygeos.io
    :members:

diff --git a/docs/linear.rst b/docs/linear.rst
@@ -1,4 +1,4 @@
-:mod:`pygeos.linear`
+Linestring operations
 =====================
 
 .. automodule:: pygeos.linear

diff --git a/docs/measurement.rst b/docs/measurement.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.measurement`
-=========================
+Measurement
+===========
 
 .. automodule:: pygeos.measurement
    :members:

diff --git a/docs/predicates.rst b/docs/predicates.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.predicates`
-========================
+Predicates
+==========
 
 .. automodule:: pygeos.predicates
    :members:

diff --git a/docs/set_operations.rst b/docs/set_operations.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.set_operations`
-=============================
+Set operations
+==============
 
 .. automodule:: pygeos.set_operations
    :members:

diff --git a/docs/strtree.rst b/docs/strtree.rst
@@ -1,5 +1,5 @@
-:mod:`pygeos.strtree`
-=====================
+STRTree
+=======
 
 .. automodule:: pygeos.strtree
    :members: STRtree