Merge pull request #41 from kjordahl/doc/revamp_docs

Documentation updates

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+Guidelines
+==========
+
+Contributions to GeoPandas are very welcome.  They are likely to
+be accepted more quickly if they follow these guidelines.
+
+At this stage of GeoPandas development, the priorities are to define a
+simple, usable, and stable API and to have clean, maintainable,
+readable code.  Performance matters, but not at the expense of those
+goals.
+
+In general, GeoPandas follows the conventions of the pandas project
+where applicable.  Please read [pandas contributing
+guidelines](https://github.com/pydata/pandas/blob/master/CONTRIBUTING.md).
+
+In particular, when submitting a pull request:
+
+- All existing tests should pass.  Please make sure that the test
+  suite passes, both locally and on
+  [Travis CI](https://travis-ci.org/kjordahl/geopandas).  Status on
+  Travis will be visible on a pull request.  If you want to enable
+  Travis CI on your own fork, please read the pandas guidelines link
+  above or the
+  [getting started docs](http://about.travis-ci.org/docs/user/getting-started/).
+
+- New functionality should include tests.  Please write reasonable
+  tests for your code and make sure that they pass on your pull request.
+
+- Classes, methods, functions, etc. should have docstrings.  The first
+  line of a docstring should be a standalone summary.  Parameters and
+  return values should be ducumented explicitly.
+
+Improving the documentation and testing for code already in GeoPandas
+is a great way to get started if you'd like to make a contribution.
+
+Style
+-----
+
+- Follow PEP 8 when possible.
+
+- Imports should be grouped with standard library imports first,
+  3rd-party libraries next, and geopandas imports third.  Within each
+  grouping, imports should be alphabetized.  Always use absolute
+  imports rather than relative imports.

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013, Enthought, Inc.
+Copyright (c) 2013, GeoPandas developers.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

doc/Makefile

@@ -5,14 +5,14 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 

doc/_templates/layout.html

@@ -1,11 +0,0 @@
-{% extends "!layout.html" %}
-{%- set rellinks = [] %}
-{% block rootrellink %}</pre>
-<ul>
-    <li><a href="index.html">Home</a> |</li>
-    <li><a href="install.html">Install</a> |</li>
-    <li><a href="docs.html">Documentation</a> |</li>
-    <li><a href="about.html">About</a> |</li>
-    <li>{% endblock %}
-{% block relbar2 %}
-{% endblock %}

doc/make.bat

@@ -5,9 +5,9 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

doc/source/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 # GeoPandas documentation build configuration file, created by
-# sphinx-quickstart on Sun Jun 30 15:18:48 2013.
+# sphinx-quickstart on Tue Oct 15 08:08:14 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
@@ -41,16 +41,18 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'GeoPandas'
-copyright = u'2013, Kelsey Jordahl'
+copyright = u'2013, GeoPandas developers'
 
 # 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.
-#
-# The short X.Y version.
-version = '0.1dev'
-# The full version, including alpha/beta/rc tags.
-release = '0.1dev'
+d = {}
+try:
+    execfile(os.path.join('..', '..', 'geopandas', 'version.py'), d)
+    version = release = d['version']
+except:
+    # FIXME: This shouldn't be hardwired, but should be set one place only
+    version = release = '0.1.0.dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -64,7 +66,7 @@ release = '0.1dev'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -103,10 +105,10 @@ html_theme = 'nature'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = "GeoPandas"
+#html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = "GeoPandas"
+#html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
@@ -131,7 +133,7 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {'**':['localtoc.html','searchbox.html']}
+#html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/source/index.rst

@@ -1,5 +1,5 @@
-GeoPandas
-=========
+GeoPandas |version|
+===================
 
 GeoPandas is an open source project to make working with geospatial
 data in python easier.  GeoPandas extends the datatypes used by
@@ -26,3 +26,14 @@ such as PostGIS.
 .. toctree::
    :maxdepth: 2
 
+  Installation <install>
+  User Guide <user>
+  About <about>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/install.rst

@@ -6,6 +6,9 @@ from `GitHub`_ and use the setup script::
 
     python setup.py install
 
+GeoPandas is also available on `PyPI`_, so ``pip install geopandas``
+should work as well.
+
 Dependencies
 ------------
 
@@ -15,6 +18,7 @@ Dependencies
 - `fiona`_
 - `descartes`_
 - `matplotlib`_
+- `geopy`_ (optional; for geocoding)
 
 Testing
 -------
@@ -25,6 +29,10 @@ To run the current set of tests from the source directory, run::
 
 from a command line.
 
+Tests are automatically run on all commits on the GitHub repository,
+including pull requests, on `Travis CI`_.
+
+.. _PyPI: https://pypi.python.org/pypi/geopandas
 .. _GitHub: https://github.com/kjordahl/geopandas
 .. _numpy: http://www.numpy.org
 .. _pandas: http://pandas.pydata.org
@@ -32,7 +40,8 @@ from a command line.
 .. _fiona: http://toblerity.github.io/fiona
 .. _Descartes: https://pypi.python.org/pypi/descartes
 .. _matplotlib: http://matplotlib.org
-
+.. _geopy: https://github.com/geopy/geopy
+.. _Travis CI: https://travis-ci.org/kjordahl/geopandas
 
 .. toctree::
    :maxdepth: 2

doc/source/user.rst

@@ -1,5 +1,5 @@
-Documentation
-=============
+GeoPandas User Guide
+====================
 
 GeoPandas implements two main data structures, a ``GeoSeries`` and a
 ``GeoDataFrame``.  These are subclasses of pandas ``Series`` and
@@ -31,7 +31,7 @@ The following Shapely methods and attributes are available on
 
   Returns a ``DataFrame`` with columns ``minx``, ``miny``, ``maxx``,
   ``maxy`` values containing the bounds for each geometry.
-  NOTE: This behavior may change in future versions.
+  (see ``GeoSeries.total_bounds`` for the limits of the entire series).
 
 .. attribute:: GeoSeries.length
 
@@ -195,6 +195,24 @@ The following Shapely methods and attributes are available on
   Returns a ``GeoSeries`` containing a simplified representation of
   each object.
 
+`Affine transformations`
+
+.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False)
+
+  Rotate the coordinates of the GeoSeries.
+
+.. method:: GeoSeries.scale(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center')
+
+ Scale the geometries of the GeoSeries along each (x, y, z) dimensio.
+
+.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False)
+
+  Shear/Skew the geometries of the GeoSeries by angles along x and y dimensions.
+
+.. method:: GeoSeries.translate(self, angle, origin='center', use_radians=False)
+
+  Shift the coordinates of the GeoSeries.
+
 `Aggregating methods`
 
 .. attribute:: GeoSeries.unary_union
@@ -221,12 +239,21 @@ Additionally, the following methods are implemented:
   Objects crossing the dateline (or other projection boundary) will
   have undesirable behavior.
 
-.. method:: GeoSeries.plot(colormap='Set1')
+.. method:: GeoSeries.plot(colormap='Set1', alpha=0.5, axes=None)
 
   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.
+  Wraps the ``plot_series()`` function.
+
+.. attribute:: GeoSeries.total_bounds
+
+  Returns a tuple containing ``minx``, ``miny``, ``maxx``,
+  ``maxy`` values for the bounds of the series as a whole.
+  See ``GeoSeries.bounds`` for the bounds of the geometries contained
+  in the series.
+
 
 Methods of pandas ``Series`` objects are also available, although not
 all are applicable to geometric objects and some may return a
@@ -241,12 +268,17 @@ 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``:
+Currently, the following methods are implemented for a ``GeoDataFrame``:
 
-.. method:: GeoDataFrame.from_file()
+.. classmethod:: GeoDataFrame.from_file(filename, **kwargs)
 
   Load a ``GeoDataFrame`` from a file from any format recognized by
-  `fiona`_.
+  `fiona`_.  See ``read_file()``.
+
+.. classmethod:: GeoDataFrame.from_postgis(sql, con, geom_col='geom', crs=None, index_col=None, coerce_float=True, params=None)
+
+  Load a ``GeoDataFrame`` from a file from a PostGIS database.
+  See ``read_postgis()``.
 
 .. method:: GeoSeries.to_crs(crs=None, epsg=None, inplace=False)
 
@@ -263,18 +295,42 @@ Currently only the following methods are implemented for a ``GeoDataFrame``:
   Objects crossing the dateline (or other projection boundary) will
   have undesirable behavior.
 
-.. method:: GeoDataFrame.plot()
+.. method:: GeoSeries.to_file(filename, driver="ESRI Shapefile", **kwargs)
 
-  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.
+  Write the ``GeoDataFrame`` to a file.  By default, an ESRI shapefile
+  is written, but any OGR data source supported by Fiona can be
+  written.  ``**kwargs`` are passed to the Fiona driver.
+
+.. method:: GeoSeries.to_json(**kwargs)
+
+  Returns a GeoJSON representation of the ``GeoDataFrame`` as a string.
+
+.. method:: GeoDataFrame.plot(column=None, colormap=None, alpha=0.5, categorical=False, legend=False, axes=None)
+
+  Generate a plot of the geometries in the ``GeoDataFrame``.  If the
+  ``column`` parameter is given, colors plot according to values in
+  that column, otherwise calls ``GeoSeries.plot()`` on the
+  ``geometry`` column.  Wraps the ``plot_dataframe()`` function.
 
 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.
 
+Geopandas functions
+-------------------
+
+.. function:: geopandas.geocode.geocode(strings, provider='googlev3', **kwargs)
+
+  Geocode a list of strings and return a GeoDataFrame containing the
+  resulting points in its ``geometry`` column.  Available
+  ``provider``s include ``googlev3``, ``bing``, ``google``, ``yahoo``,
+  ``mapquest``, and ``openmapquest``.  ``**kwargs`` will be passed as
+  parameters to the appropriate geocoder.
+
+  Requires `geopy`_.  Please consult the Terms of Service for the
+  chosen provider.
+
 Examples
 --------
 
@@ -423,6 +479,7 @@ borough that are in the holes:
 .. _Descartes: https://pypi.python.org/pypi/descartes
 .. _matplotlib: http://matplotlib.org
 .. _fiona: http://toblerity.github.io/fiona
+.. _geopy: https://github.com/geopy/geopy
 .. _file containing the boroughs of New York City: http://www.nyc.gov/html/dcp/download/bytes/nybb_13a.zip
 
 .. toctree::