Merge pull request #150 from xylar/simplify_docs

Simplify and update the documentation

Author: xylar

docs/api.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: geometric_features
+
 #############
 API reference
 #############
@@ -9,8 +11,6 @@ the documentation.
 Command-line scripts
 ====================
 
-.. currentmodule:: geometric_features.__main__
-
 .. autosummary::
    :toctree: generated/
 
@@ -28,22 +28,46 @@ Command-line scripts
 Python package
 ==============
 
-.. currentmodule:: geometric_features.geometric_features
+Reading Geometric Features
+--------------------------
 
 .. autosummary::
    :toctree: generated/
 
    GeometricFeatures
    GeometricFeatures.read
+
+Splitting new data into Geometric Features
+------------------------------------------
+
+.. autosummary::
+   :toctree: generated/
+
    GeometricFeatures.split
+   write_feature_names_and_tags
 
-.. currentmodule:: geometric_features.feature_collection
+Reading a Feature Collection
+----------------------------
 
 .. autosummary::
    :toctree: generated/
 
    read_feature_collection
+
+Creating a Feature Collection
+-----------------------------
+
+.. autosummary::
+   :toctree: generated/
+
    FeatureCollection
+
+Manipulating a Feature Collection
+---------------------------------
+
+.. autosummary::
+   :toctree: generated/
+
    FeatureCollection.add_feature
    FeatureCollection.merge
    FeatureCollection.tag

docs/feature_collection.rst

@@ -11,7 +11,7 @@ Reading in Features
 -------------------
 
 A ``FeatureCollection`` can be read from a file with the function
-:func:`geometric_features.feature_collection.read_feature_collection`:
+:func:`geometric_features.read_feature_collection`:
 
 .. code-block:: python
 
@@ -23,7 +23,7 @@ Add a Feature
 -------------
 
 To add a single feature to a ``FeatureColleciton``, use
-:meth:`geometric_features.feature_collection.FeatureCollection.add_feature`:
+:meth:`geometric_features.FeatureCollection.add_feature`:
 
 .. code-block:: python
 
@@ -35,7 +35,7 @@ Merging Features
 ----------------
 
 A ``FeatureCollection`` ``fc2`` can be merged into another colleciton ``fc1``
- with :meth:`geometric_features.feature_collection.FeatureCollection.merge`:
+ with :meth:`geometric_features.FeatureCollection.merge`:
 
 .. code-block:: python
 
@@ -48,7 +48,7 @@ Plotting Features
 -----------------
 
 A ``FeatureCollection`` can be plotted on a given map projeciton with
-:meth:`geometric_features.feature_collection.FeatureCollection.plot`:
+:meth:`geometric_features.FeatureCollection.plot`:
 
 .. code-block:: python
 
@@ -63,7 +63,7 @@ Tag Features
 ------------
 
 All the features in a ``FeatureCollection`` can be tagged with one or more tags
-using :meth:`geometric_features.feature_collection.FeatureCollection.tag`:
+using :meth:`geometric_features.FeatureCollection.tag`:
 
 .. code-block:: python
 
@@ -78,7 +78,7 @@ Writing out Features
 --------------------
 
 To write out a ``FeatureCollection`` to a ``geojson`` file, call
-:meth:`geometric_features.feature_collection.FeatureCollection.to_geojson`
+:meth:`geometric_features.FeatureCollection.to_geojson`
 
 .. code-block:: python
 
@@ -88,7 +88,7 @@ Set a Group Name
 ----------------
 
 To set the ``groupName`` property of a ``FeatureCollection``, call
-:meth:`geometric_features.feature_collection.FeatureCollection.set_group_name`.
+:meth:`geometric_features.FeatureCollection.set_group_name`.
 
 .. code-block:: python
 
@@ -105,7 +105,7 @@ Combine Features
 
 Features in a ``FeatureCollection`` can be combined (fused together into a
 single feature) using
-:meth:`geometric_features.feature_collection.FeatureCollection.combine`:
+:meth:`geometric_features.FeatureCollection.combine`:
 
 .. code-block:: python
 
@@ -117,7 +117,7 @@ Difference Features
 
 Features in a ``FeatureCollection`` can be masked with one or more masking
 features from another ``FeatureCollection`` using
-:meth:`geometric_features.feature_collection.FeatureCollection.difference`:
+:meth:`geometric_features.FeatureCollection.difference`:
 
 .. code-block:: python
 
@@ -132,7 +132,7 @@ Simplify Features
 Sometimes, features are made up of segments or polygons with tiny edges that
 add little relevant detail to the features but make the files describing them
 needlessly large.  In such cases, the features can be simplified by calling
-:meth:`geometric_features.feature_collection.FeatureCollection.simplify` with
+:meth:`geometric_features.FeatureCollection.simplify` with
 and appropriate length scale (in degrees latitude/longitude) over which the
 feature may be modified to make it simpler.  If a length scale of zero is
 used, the feature will be simplified without any modification tot he shape
@@ -153,7 +153,7 @@ provides a bit of a hack for removing a tiny sliver of the feature around the
 antimeridian so that the resulting shape remians between -180 and 180 degrees
 longitude.
 
-:meth:`geometric_features.feature_collection.FeatureCollection.fix_antimeridian`
+:meth:`geometric_features.FeatureCollection.fix_antimeridian`
 
 .. code-block:: python
 

docs/geometric_data.rst

@@ -5,19 +5,22 @@ Geometric Data
 
 The the overarching purpose of ``geometric_features`` is to facilitate access
 to and manipulation of the geometric data in the repository.  This data is
-currently divided across 5 components, ``bedmap2``, ``iceshelves``,
-``landice``,  ``natural_earth``, and  ``ocean``.
+currently divided across 6 components, ``bedmachine``, ``bedmap2``,
+``iceshelves``, ``landice``,  ``natural_earth``, and  ``ocean``.
 
 Components
 ----------
 
-bedmap2
-^^^^^^^
+bedmachine and bedmap2
+^^^^^^^^^^^^^^^^^^^^^^
 
-This component defines two "coastlines" between the Antarctic continent and
-the ocean.  One exclues the cavity under ice shelves while the other includes
-them.  The dataset used to define these coastlines is Bedmap2
-(`Fretwell et al. 2016`_).
+These components each define two "coastlines" between the Antarctic continent
+and the ocean.  One excludes the cavity under ice shelves while the other
+includes them.  The ``bedmachine`` component uses the BedMachine Antarctica
+dataset
+(`Morlighem et al. 2020 <https://www.nature.com/articles/s41561-019-0510-8>`_)
+to define the coastlines, while the ``bedmap2`` dataset is based on Bedmap2
+(`Fretwell et al. 2016 <http://www.the-cryosphere.net/7/375/2013/>`_).
 
 iceshelves
 ^^^^^^^^^^
@@ -176,7 +179,7 @@ Here are two simple examples of features from the repository:
             ]
         }
 
-.. _`Fretwell et al. 2016`: http://www.the-cryosphere.net/7/375/2013/
+
 .. _`IMBIE1 Basins`: http://imbie.org/imbie-2016/drainage-basins/
 .. _`Natural Earth`: http://www.naturalearthdata.com/
 .. _`International Hydrographic Organisation`: http://www.marineregions.org/downloads.php#iho

geometric_features/__init__.py

@@ -6,5 +6,12 @@
 from geometric_features.feature_collection import FeatureCollection, \
      read_feature_collection
 
+from geometric_features.__main__ import combine_features, difference_features, \
+    fix_features_at_antimeridian, merge_features, plot_features, \
+    set_group_name, split_features, simplify_features, tag_features
+
+from geometric_features.utils import write_feature_names_and_tags
+
+
 __version_info__ = (0, 1, 11)
 __version__ = '.'.join(str(vi) for vi in __version_info__)

geometric_features/feature_collection.py

@@ -35,7 +35,7 @@ def read_feature_collection(fileName):
 
     Returns
     -------
-    fc : ``FeatureCollection``
+    fc : geometric_features.FeatureCollection
         The feature collection read in
     '''
     # Authors
@@ -121,7 +121,7 @@ def merge(self, other):
 
         Parameters
         ----------
-        other : ``FeatureCollection``
+        other : geometric_features.FeatureCollection
             The other feature collection
         '''
         # Authors
@@ -184,7 +184,7 @@ def combine(self, featureName):
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             A new feature collection with a single feature with the combined
             geometry
 
@@ -242,15 +242,15 @@ def difference(self, maskingFC, show_progress=False):
 
         Parameters
         ----------
-        maskingFC : ``FeatureCollection```
+        maskingFC : geometric_features.FeatureCollection
             Another collection of one or more features to use as masks
 
         show_progress : bool
             Show a progress bar
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             A new feature collection with a single feature with the geometry
             masked
         '''
@@ -321,7 +321,7 @@ def fix_antimeridian(self):
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             A new feature collection with the antimeridian handled correctly
         '''
         # Authors
@@ -355,7 +355,7 @@ def simplify(self, tolerance=0.0):
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             A new feature collection with simplified geometries
         '''
         # Authors

geometric_features/geometric_features.py

@@ -100,7 +100,7 @@ def read(self, componentName, objectType, featureNames=None, tags=None,
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             The feature collection read in
         '''
         # Authors
@@ -125,7 +125,7 @@ def split(self, fc, destinationDir=None):
 
         Parameters
         ----------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             The feature collection to split
 
         destinationDir : str, optional
@@ -134,7 +134,7 @@ def split(self, fc, destinationDir=None):
 
         Returns
         -------
-        fc : ``FeatureCollection``
+        fc : geometric_features.FeatureCollection
             The feature collection read in
         '''
         # Authors

geometric_features/test/test_set_group_name.py

@@ -22,7 +22,7 @@ def test_assign_groupname(self, componentName='ocean', objectType='region',
 
         Parameters
         ----------
-         componentName : {'bedmap2', 'iceshelves', 'landice', 'natural_earth', 'ocean'}, optional
+         componentName : {'bedmachine', 'bedmap2', 'iceshelves', 'landice', 'natural_earth', 'ocean'}, optional
             The component from which to retieve the feature
 
         objectType : {'point', 'transect', 'region'}, optional