DOC: Regenerate sphinx autodoc files and move files to source dir

2026-09-11 12:10:59 +08:00 · 2013-10-22 21:45:21 -04:00
parent 8144a45ed8
commit 5e55a4063f
14 changed files with 14 additions and 27 deletions
@@ -0,0 +1,9 @@
+About
+=====
+
+Coming soon...
+
+
+.. toctree::
+   :maxdepth: 2
+
@@ -0,0 +1,240 @@
+# -*- coding: utf-8 -*-
+#
+# GeoPandas documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct 15 08:08:14 2013.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'GeoPandas'
+copyright = u'2013, Kelsey Jordahl'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+d = {}
+execfile(os.path.join('..', '..', 'geopandas', 'version.py'), d)
+version = release = d['version']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'nature'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'GeoPandasdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'GeoPandas.tex', u'GeoPandas Documentation',
+   u'Kelsey Jordahl', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'geopandas', u'GeoPandas Documentation',
+     [u'Kelsey Jordahl'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'GeoPandas', u'GeoPandas Documentation',
+   u'Kelsey Jordahl', 'GeoPandas', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
@@ -0,0 +1,28 @@
+GeoPandas
+=========
+
+GeoPandas is an open source project to make working with geospatial
+data in python easier.  GeoPandas extends the datatypes used by
+`pandas`_ to allow spatial operations on geometric types.  Geometric
+operations are performed by `shapely`_.  Geopandas further depends on
+`fiona`_ for file access and `descartes`_ and `matplotlib`_ for plotting.
+
+.. _pandas: http://pandas.pydata.org
+.. _shapely: http://toblerity.github.io/shapely
+.. _fiona: http://toblerity.github.io/fiona
+.. _Descartes: https://pypi.python.org/pypi/descartes
+.. _matplotlib: http://matplotlib.org
+
+Description
+-----------
+
+The goal of GeoPandas is to make working with geospatial data in
+python easier.  It combines the capabilities of pandas and shapely,
+providing geospatial operations in pandas and a high-level interface
+to multiple geometries to shapely.  GeoPandas enables you to easily do
+operations in python that would otherwise require a spatial database
+such as PostGIS.
+
+.. toctree::
+   :maxdepth: 2
+
@@ -0,0 +1,39 @@
+Installation
+============
+
+GeoPandas is pre-alpha software.  Please install the latest source
+from `GitHub`_ and use the setup script::
+
+    python setup.py install
+
+Dependencies
+------------
+
+- `numpy`_
+- `pandas`_
+- `shapely`_
+- `fiona`_
+- `descartes`_
+- `matplotlib`_
+
+Testing
+-------
+
+To run the current set of tests from the source directory, run::
+
+    nosetests -v
+
+from a command line.
+
+.. _GitHub: https://github.com/kjordahl/geopandas
+.. _numpy: http://www.numpy.org
+.. _pandas: http://pandas.pydata.org
+.. _shapely: http://toblerity.github.io/shapely
+.. _fiona: http://toblerity.github.io/fiona
+.. _Descartes: https://pypi.python.org/pypi/descartes
+.. _matplotlib: http://matplotlib.org
+
+
+.. toctree::
+   :maxdepth: 2
+
@@ -0,0 +1,431 @@
+Documentation
+=============
+
+GeoPandas implements two main data structures, a ``GeoSeries`` and a
+``GeoDataFrame``.  These are subclasses of pandas ``Series`` and
+``DataFrame``, respectively.
+
+GeoSeries
+---------
+
+A ``GeoSeries`` contains a sequence of geometries.
+
+The ``GeoSeries`` class implements nearly all of the attributes and
+methods of Shapely objects.  When applied to a ``GeoSeries``, they
+will apply elementwise to all geometries in the series.  Binary
+operations can be applied between two ``GeoSeries``, in which case the
+operation is carried out elementwise.  The two series will be aligned
+by matching indices.  Binary operations can also be applied to a
+single geometry, in which case the operation is carried out for each
+element of the series with that geometry.  In either case, a
+``Series`` or a ``GeoSeries`` will be returned, as appropriate.
+
+The following Shapely methods and attributes are available on
+``GeoSeries`` objects:
+
+.. attribute:: GeoSeries.area
+
+  Returns a ``Series`` containing the area of each geometry in the ``GeoSeries``.
+
+.. attribute:: GeoSeries.bounds
+
+  Returns a ``DataFrame`` with columns ``minx``, ``miny``, ``maxx``,
+  ``maxy`` values containing the bounds for each geometry.
+  NOTE: This behavior may change in future versions.
+
+.. attribute:: GeoSeries.length
+
+  Returns a ``Series`` containing the length of each geometry.
+
+.. attribute:: GeoSeries.geom_type
+
+  Returns a ``Series`` of strings specifying the `Geometry Type` of
+  each object.
+
+.. method:: GeoSeries.distance(other)
+
+  Returns a ``Series`` containing the minimum distance to the `other`
+  ``GeoSeries`` (elementwise) or geometric object.
+
+.. method:: GeoSeries.representative_point()
+
+  Returns a ``GeoSeries`` of (cheaply computed) points that are
+  guaranteed to be within each geometry.
+
+.. attribute:: GeoSeries.exterior
+
+  Returns a ``GeoSeries`` of LinearRings representing the outer
+  boundary of each polygon in the GeoSeries.  (Applies to GeoSeries
+  containing only Polygons).
+
+.. attribute:: GeoSeries.interiors
+
+  Returns a ``GeoSeries`` of InteriorRingSequences representing the
+  inner rings of each polygon in the GeoSeries.  (Applies to GeoSeries
+  containing only Polygons).
+
+`Unary Predicates`
+
+.. attribute:: GeoSeries.is_empty
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
+  empty geometries.
+
+.. attribute:: GeoSeries.is_ring
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
+  features that are closed.
+
+.. attribute:: GeoSeries.is_simple
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
+  geometries that do not cross themselves (meaningful only for
+  `LineStrings` and `LinearRings`).
+
+.. attribute:: GeoSeries.is_valid
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
+  geometries that are valid.
+
+`Binary Predicates`
+
+.. method:: GeoSeries.almost_equals(other[, decimal=6])
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  each object is approximately equal to the `other` at all
+  points to specified `decimal` place precision.  (See also :meth:`equals`)
+
+.. method:: GeoSeries.contains(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  each object's `interior` contains the `boundary` and
+  `interior` of the other object and their boundaries do not touch at all.
+
+.. method:: GeoSeries.crosses(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  the `interior` of each object intersects the `interior` of
+  the other but does not contain it, and the dimension of the intersection is
+  less than the dimension of the one or the other.
+
+.. method:: GeoSeries.disjoint(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  the `boundary` and `interior` of each object does not
+  intersect at all with those of the other.
+
+.. method:: GeoSeries.equals(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  if the set-theoretic `boundary`, `interior`, and `exterior`
+  of each object coincides with those of the other.
+
+.. method:: GeoSeries.intersects(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  if the `boundary` and `interior` of each object intersects in
+  any way with those of the other.
+
+.. method:: GeoSeries.touches(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  the objects have at least one point in common and their
+  interiors do not intersect with any part of the other.
+
+.. method:: GeoSeries.within(other)
+
+  Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if
+  each object's `boundary` and `interior` intersect only
+  with the `interior` of the other (not its `boundary` or `exterior`).
+  (Inverse of :meth:`contains`)
+
+`Set-theoretic Methods`
+
+.. attribute:: GeoSeries.boundary
+
+  Returns a ``GeoSeries`` of lower dimensional objects representing
+  each geometries's set-theoretic `boundary`.
+
+.. attribute:: GeoSeries.centroid
+
+  Returns a ``GeoSeries`` of points for each geometric centroid.
+
+.. method:: GeoSeries.difference(other)
+
+  Returns a ``GeoSeries`` of the points in each geometry that
+  are not in the *other* object.
+
+.. method:: GeoSeries.intersection(other)
+
+  Returns a ``GeoSeries`` of the intersection of each object with the `other`
+  geometric object.
+
+.. method:: GeoSeries.symmetric_difference(other)
+
+  Returns a ``GeoSeries`` of the points in each object not in the `other`
+  geometric object, and the points in the `other` not in this object.
+
+.. method:: GeoSeries.union(other)
+
+  Returns a ``GeoSeries`` of the union of points from each object and the
+  `other` geometric object.
+
+`Constructive Methods`
+
+.. method:: GeoSeries.buffer(distance, resolution=16)
+
+  Returns a ``GeoSeries`` of geometries representing all points within a given `distance`
+  of each geometric object.
+
+.. attribute:: GeoSeries.convex_hull
+
+  Returns a ``GeoSeries`` of geometries representing the smallest
+  convex `Polygon` containing all the points in each object unless the
+  number of points in the object is less than three. For two points,
+  the convex hull collapses to a `LineString`; for 1, a `Point`.
+
+.. attribute:: GeoSeries.envelope
+
+  Returns a ``GeoSeries`` of geometries representing the point or
+  smallest rectangular polygon (with sides parallel to the coordinate
+  axes) that contains each object.
+
+.. method:: GeoSeries.simplify(tolerance, preserve_topology=True)
+
+  Returns a ``GeoSeries`` containing a simplified representation of
+  each object.
+
+`Aggregating methods`
+
+.. attribute:: GeoSeries.unary_union
+
+  Return a geometry containing the union of all geometries in the ``GeoSeries``.
+
+Additionally, the following methods are implemented:
+
+.. method:: GeoSeries.from_file()
+
+  Load a ``GeoSeries`` from a file from any format recognized by
+  `fiona`_.
+
+.. method:: GeoSeries.to_crs(crs=None, epsg=None)
+
+  Transform all geometries in a GeoSeries to a different coordinate
+  reference system.  The ``crs`` attribute on the current GeoSeries
+  must be set.  Either ``crs`` in dictionary form or an EPSG code may
+  be specified for output.
+
+  This method will transform all points in all objects.  It has no
+  notion or projecting entire geometries.  All segments joining points
+  are assumed to be lines in the current projection, not geodesics.
+  Objects crossing the dateline (or other projection boundary) will
+  have undesirable behavior.
+
+.. method:: GeoSeries.plot(colormap='Set1')
+
+  Generate a plot of the geometries in the ``GeoSeries``.
+  ``colormap`` can be any recognized by matplotlib, but discrete
+  colormaps such as ``Accent``, ``Dark2``, ``Paired``, ``Pastel1``,
+  ``Pastel2``, ``Set1``, ``Set2``, or ``Set3`` are recommended.
+
+Methods of pandas ``Series`` objects are also available, although not
+all are applicable to geometric objects and some may return a
+``Series`` rather than a ``GeoSeries`` result.  The methods
+``copy()``, ``align()``, ``isnull()`` and ``fillna()`` have been
+implemented specifically for ``GeoSeries`` and are expected to work
+correctly.
+
+GeoDataFrame
+------------
+
+A ``GeoDataFrame`` is a tablular data structure that contains a column
+called ``geometry`` which contains a `GeoSeries``.
+
+Currently only the following methods are implemented for a ``GeoDataFrame``:
+
+.. method:: GeoDataFrame.from_file()
+
+  Load a ``GeoDataFrame`` from a file from any format recognized by
+  `fiona`_.
+
+.. method:: GeoSeries.to_crs(crs=None, epsg=None, inplace=False)
+
+  Transform all geometries in the ``geometry`` column of a
+  GeoDataFrame to a different coordinate reference system.  The
+  ``crs`` attribute on the current GeoSeries must be set.  Either
+  ``crs`` in dictionary form or an EPSG code may be specified for
+  output.  If ``inplace=True`` the geometry column will be replaced in
+  the current dataframe, otherwise a new GeoDataFrame will be returned.
+
+  This method will transform all points in all objects.  It has no
+  notion or projecting entire geometries.  All segments joining points
+  are assumed to be lines in the current projection, not geodesics.
+  Objects crossing the dateline (or other projection boundary) will
+  have undesirable behavior.
+
+.. method:: GeoDataFrame.plot()
+
+  Generate a plot of the geometries in the ``GeoDataFrame``.
+  Currently calls ``GeoSeries.plot()`` on the ``geometry`` column,
+  though in the future this will be able to color the geometries by
+  data values from another column.
+
+All pandas ``DataFrame`` methods are also available, although they may
+not operate in a meaningful way on the ``geometry`` column and may not
+return a ``GeoDataFrame`` result even when it would be appropriate to
+do so.
+
+Examples
+--------
+
+.. sourcecode:: python
+
+    >>> p1 = Polygon([(0, 0), (1, 0), (1, 1)])
+    >>> p2 = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
+    >>> p3 = Polygon([(2, 0), (3, 0), (3, 1), (2, 1)])
+    >>> g = GeoSeries([p1, p2, p3])
+    >>> g
+    0    POLYGON ((0.0000000000000000 0.000000000000000...
+    1    POLYGON ((0.0000000000000000 0.000000000000000...
+    2    POLYGON ((2.0000000000000000 0.000000000000000...
+    dtype: object
+
+.. image:: _static/test.png
+
+Some geographic operations return normal pandas object.  The ``area`` property of a ``GeoSeries`` will return a ``pandas.Series`` containing the area of each item in the ``GeoSeries``:
+
+.. sourcecode:: python
+
+    >>> print g.area
+    0    0.5
+    1    1.0
+    2    1.0
+    dtype: float64
+
+Other operations return GeoPandas objects:
+
+.. sourcecode:: python
+
+    >>> g.buffer(0.5)
+    Out[15]:
+    0    POLYGON ((-0.3535533905932737 0.35355339059327...
+    1    POLYGON ((-0.5000000000000000 0.00000000000000...
+    2    POLYGON ((1.5000000000000000 0.000000000000000...
+    dtype: object
+
+.. image:: _static/test_buffer.png
+
+GeoPandas objects also know how to plot themselves.  GeoPandas uses `descartes`_ to generate a `matplotlib`_ plot. To generate a plot of our GeoSeries, use:
+
+.. sourcecode:: python
+
+    >>> g.plot()
+
+GeoPandas also implements alternate constructors that can read any data format recognized by `fiona`_.  To read a `file containing the boroughs of New York City`_:
+
+.. sourcecode:: python
+
+    >>> boros = GeoDataFrame.from_file('nybb.shp')
+    >>> boros.set_index('BoroCode', inplace=True)
+    >>> boros.sort()
+    >>> boros
+                   BoroName    Shape_Area     Shape_Leng  \
+    BoroCode
+    1             Manhattan  6.364422e+08  358532.956418
+    2                 Bronx  1.186804e+09  464517.890553
+    3              Brooklyn  1.959432e+09  726568.946340
+    4                Queens  3.049947e+09  861038.479299
+    5         Staten Island  1.623853e+09  330385.036974
+    
+                                                       geometry
+    BoroCode
+    1         (POLYGON ((981219.0557861328125000 188655.3157...
+    2         (POLYGON ((1012821.8057861328125000 229228.264...
+    3         (POLYGON ((1021176.4790039062500000 151374.796...
+    4         (POLYGON ((1029606.0765991210937500 156073.814...
+    5         (POLYGON ((970217.0223999023437500 145643.3322...
+
+.. image:: _static/nyc.png
+ 
+.. sourcecode:: python
+
+    >>> boros['geometry'].convex_hull
+    0    POLYGON ((915517.6877458114176989 120121.88125...
+    1    POLYGON ((1000721.5317993164062500 136681.7761...
+    2    POLYGON ((988872.8212280273437500 146772.03179...
+    3    POLYGON ((977855.4451904296875000 188082.32238...
+    4    POLYGON ((1017949.9776000976562500 225426.8845...
+    dtype: object
+
+.. image:: _static/nyc_hull.png
+
+To demonstrate a more complex operation, we'll generate a
+``GeoSeries`` containing 2000 random points:
+
+.. sourcecode:: python
+
+    >>> from shapely.geometry import Point
+    >>> xmin, xmax, ymin, ymax = 900000, 1080000, 120000, 280000
+    >>> xc = (xmax - xmin) * np.random.random(2000) + xmin
+    >>> yc = (ymax - ymin) * np.random.random(2000) + ymin
+    >>> pts = GeoSeries([Point(x, y) for x, y in zip(xc, yc)])
+
+Now draw a circle with fixed radius around each point:
+
+.. sourcecode:: python
+
+    >>> circles = pts.buffer(2000)
+
+We can collapse these circles into a single shapely MultiPolygon
+geometry with
+
+.. sourcecode:: python
+
+    >>> mp = circles.unary_union
+
+To extract the part of this geometry contained in each borough, we can
+just use:
+
+.. sourcecode:: python
+
+    >>> holes = boros['geometry'].intersection(mp)
+
+.. image:: _static/holes.png
+ 
+and to get the area outside of the holes:
+
+.. sourcecode:: python
+
+    >>> boros_with_holes = boros['geometry'].difference(mp)
+
+.. image:: _static/boros_with_holes.png
+ 
+Note that this can be simplified a bit, since ``geometry`` is
+available as an attribute on a ``GeoDataFrame``, and the
+``intersection`` and ``difference`` methods are implemented with the
+"&" and "-" operators, respectively.  For example, the latter could
+have been expressed simply as ``boros.geometry - mp``.
+
+It's easy to do things like calculate the fractional area in each
+borough that are in the holes:
+
+.. sourcecode:: python
+
+    >>> holes.area / boros.geometry.area
+    BoroCode
+    1           0.602015
+    2           0.523457
+    3           0.585901
+    4           0.577020
+    5           0.559507
+    dtype: float64
+
+.. _Descartes: https://pypi.python.org/pypi/descartes
+.. _matplotlib: http://matplotlib.org
+.. _fiona: http://toblerity.github.io/fiona
+.. _file containing the boroughs of New York City: http://www.nyc.gov/html/dcp/download/bytes/nybb_13a.zip
+
+.. toctree::
+   :maxdepth: 2
+
+