Merge pull request #1027 from pelson/docs_reordering

Re-worded some of the homepage, re-ordered some of the userguide.

INSTALL

@@ -50,7 +50,7 @@ you may need to install the development packages (look for a "-dev"
 suffix) in addition to the core packages.  
 
 Many of these dependencies are built as part of Cartopy's conda distribution.
-The recipes for these can be found at https://github.com/SciTools/conda-recipes-scitools.
+The recipes for these can be found at `https://github.com/conda-forge/feedstocks`_.
 
 
 **Python** 2.7 or later (https://www.python.org/)

docs/source/_static/layout.css

@@ -27,3 +27,8 @@ div.section div.figure {
   padding-left: 0 !important;
   text-align: center;
 }
+
+pre a {
+    // Prevent code examples showing underlines.
+    text-decoration: none !important;
+}

docs/source/crs/index.rst

@@ -5,7 +5,7 @@ The :class:`cartopy.crs.CRS` class is the very core of cartopy, all coordinate r
 in cartopy have :class:`~cartopy.crs.CRS` as a parent class, meaning all projections have
 the interface described below.
 
-.. autoclass:: cartopy.crs.CRS(proj4_params, globe=None)
+.. autoclass:: cartopy.crs.CRS()
    :members:
 
    .. data:: globe

docs/source/index.rst

@@ -9,40 +9,36 @@
 Introduction
 ============
 
-Cartopy is a Python package designed to make drawing maps for data analysis and visualisation as easy as possible.
+Cartopy is a Python package designed for geospatial data processing in order to produce maps and other geospatial data analyses.
 
-Cartopy makes use of the powerful PROJ.4, numpy and shapely libraries and has a simple and intuitive
-drawing interface to Matplotlib for creating publication quality maps.
+Cartopy makes use of the powerful PROJ.4, numpy and shapely libraries and includes a programatic interface
+built on top of Matplotlib for the creation of publication quality maps.
 
-Some of the key features of cartopy are:
+Key features of cartopy are its object oriented :ref:`projection definitions <cartopy_projections>`, and its
+ability to transform points, lines, vectors, polygons and images between those projections.
 
- * object oriented projection definitions
- * point, line, vector, polygon and image transformations between projections
- * integration to expose advanced mapping in Matplotlib with a simple and intuitive interface
- * powerful vector data handling by integrating shapefile reading with Shapely capabilities
-
-Cartopy is licensed under `GNU Lesser General Public License <https://www.gnu.org/licenses/lgpl.html>`_
-and is at version |version|. You can find the source code for cartopy on
-`our github page <https://github.com/SciTools/cartopy>`_.
+You will find cartopy especially useful for large area / small scale data, where Cartesian
+assumptions of spherical data traditionally break down. If you've ever experienced a singularity
+at the pole or a cut-off at the dateline, it is likely you will appreciate cartopy's unique features!
 
 
 .. _getting-started-with-cartopy:
 
 Getting started
 ===============
 
-The :ref:`installation guide <installing>` provides information on getting up and running, and
-cartopy's documentation is arranged userguide form with reference documentation available inline.
+The :ref:`installation guide <installing>` provides information on getting up and running. 
+Cartopy's documentation is arranged in userguide form, with reference documentation available inline.
 
 .. toctree::
     :maxdepth: 1
 
     crs/index.rst
     crs/projections.rst
-    tutorials/using_the_shapereader.rst
-    tutorials/understanding_transform.rst
     matplotlib/intro.rst
     matplotlib/feature_interface.rst
+    tutorials/understanding_transform.rst
+    tutorials/using_the_shapereader.rst
     developer_interfaces.rst
 
 
@@ -71,25 +67,21 @@ Getting involved
 Cartopy was originally developed at the UK Met Office to allow scientists to visualise
 their data on maps quickly, easily and most importantly, accurately.
 Cartopy has been made freely available under the terms of the
-`GNU Lesser General Public License <https://www.gnu.org/licenses/lgpl.html>`_. It is suitable to be used in a variety
+`GNU Lesser General Public License <https://www.gnu.org/licenses/lgpl.html>`_.
+It is suitable to be used in a variety
 of scientific fields and has an :doc:`active development community <contributors>`.
 
 There are many ways to get involved in the development of cartopy:
 
  * If you write a paper which makes use of cartopy, please consider :doc:`citing <citation>` it.
- * If you publish the maps and plots, please consider the required :ref:`attribution of copyright  <referencing_copyright>` for the data.
+ * If you publish the maps and plots, please consider the required :ref:`attribution of copyright <referencing_copyright>` for the data.
  * Report bugs and problems with the code or documentation to https://github.com/SciTools/cartopy/issues (please look to see if there are any outstanding
    bugs which cover the issue before making a new one).
- * Help others with support questions on `stackoverflow <https://stackoverflow.com/questions/tagged/cartopy>`_.
+ * Help others with cartopy questions on `StackOverflow <https://stackoverflow.com/questions/tagged/cartopy>`_.
  * Contribute to the documentation fixing typos, adding examples, explaining things more clearly, or even
    re-designing its layout/logos etc.. The `documentation source <https://github.com/SciTools/cartopy>`_ is kept in the same repository as the source code.
  * Contribute bug fixes (:issues:`a list of outstanding bugs can be found on github <bug>`).
- * Contribute enhancements and new features
-   (:issues:`a wish list of features can also be found on github <wishlist>`).
-
-Development discussion takes place on the `matplotlib-devel mailing list
-<http://matplotlib.1069221.n5.nabble.com/matplotlib-devel-f28077.html>`_ with all discussion
-subjects prefixed with "cartopy: ".
+ * Contribute enhancements and new features on the issue tracker.
 
 
 

docs/source/matplotlib/advanced_plotting.rst

@@ -135,9 +135,9 @@ Vector plotting
 
 Cartopy comes with powerful vector field plotting functionality. There are 3 distinct options for
 visualising vector fields:
-:meth:`quivers <cartopy.mpl.geoaxes.GeoAxes.quiver>` (:ref:`example <examples-arrows>`),
-:meth:`barbs <cartopy.mpl.geoaxes.GeoAxes.barbs>` (:ref:`example <examples-barbs>`) and
-:meth:`streamplots <cartopy.mpl.geoaxes.GeoAxes.streamplot>` (:ref:`example <examples-streamplot>`)
+:meth:`quivers <cartopy.mpl.geoaxes.GeoAxes.quiver>` (:ref:`example <sphx_glr_gallery_arrows.py>`),
+:meth:`barbs <cartopy.mpl.geoaxes.GeoAxes.barbs>` (:ref:`example <sphx_glr_gallery_barbs.py>`) and
+:meth:`streamplots <cartopy.mpl.geoaxes.GeoAxes.streamplot>` (:ref:`example <sphx_glr_gallery_streamplot.py>`)
 each with their own benefits for displaying certain vector field forms.
 
 .. figure:: ../gallery/images/sphx_glr_arrows_001.png

docs/source/sphinxext/pre_sphinx_gallery.py

@@ -47,13 +47,12 @@ def example_groups(src_dir):
 
     for fname in sorted_listdir:
         fpath = os.path.join(src_dir, fname)
-        __tags__ = []
         with open(fpath, 'r') as fh:
             for line in fh:
                 # Crudely remove the __tags__ line.
                 if line.startswith('__tags__ = '):
                     exec(line.strip(), locals(), globals())
-                    for tag in __tags__:
+                    for tag in __tags__:  # noqa:
                         tagged_examples.setdefault(tag, []).append(fname)
                     break
             else:

docs/source/tutorials/using_the_shapereader.rst

@@ -4,8 +4,18 @@ Using the cartopy shapereader
 =============================
 
 Cartopy provides an object oriented shapefile reader based on top of the 
-`pyshp <https://github.com/GeospatialPython/pyshp>`_ module to provide easy,
-programmatic, access to standard vector datasets.
+`pyshp`_ module to provide easy, programmatic, access to standard vector datasets.
+
+Cartopy's wrapping of pyshp has the benefit of being pure python, and is therefore
+easy to install and extremely portable. However, for heavy duty shapefile I/O `Fiona`_ and
+`GeoPandas`_ are highly recommended.
+
+.. _pyshp: https://github.com/GeospatialPython/pyshp
+.. _Fiona: http://toblerity.org/fiona/
+.. _GeoPandas: http://geopandas.org/
+
+
+
 
 .. currentmodule:: cartopy.io.shapereader