Merge branch 'master' into py3k

Author: ocefpaf

docs/source/conf.py

@@ -34,6 +34,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -176,3 +177,6 @@
      author, 'ODM2PythonAPI', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+
+autosummary_generate = True

docs/source/contribute.rst

@@ -0,0 +1,37 @@
+Contribute to Documentation
+============================
+
+This guide is a reference on how to contribute to ODM2 Documentation effort
+for the many `ODM2 Software Ecosystem <https://github.com/ODM2/odm2-software-ecosystem>`__.
+
+Conventions
+-----------
+
+There are a few conventions that should be followed
+when writing docstrings within the code:
+
+- Docstrings should follow
+  `Google Style Documentation
+  <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__.
+
+- Do not say "**defaults to ____**" for any arguments,
+  unless the argument needs further explanation.
+  The default value is already available in the method/function definition.
+
+- If function needs to be instantiated, explicitly show in example.
+  See
+  `here <https://stackoverflow.com/questions/17134653/difference-between-class-and-instance-methods>`__
+  for discussion of class vs instance methods.
+
+- Provide link to `Controlled Vocabulary <http://vocabulary.odm2.org/>`__
+  if an argument needs a CV as value.
+
+Please add any additional conventions that you think should be in place
+within `the github issue #106 <https://github.com/ODM2/ODM2PythonAPI/issues/106>`__.
+
+Pull requests
+-------------
+
+Once changes has been in place within your forked copy of the repository
+you are working on, please create a pull request to add your contribution
+to the **master** branch of the repository.

docs/source/index.rst

@@ -9,12 +9,18 @@ A Python-based application programmer's interface for the `Observations Data Mod
 
    installing
    modules
-   models
+   odm2models
    credits
+   contribute
 
 Indices and tables
 ==================
 
+.. toctree::
+   :maxdepth: 2
+
+   models
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`

docs/source/models.rst

@@ -1,7 +1,27 @@
-ODM2 Models
-===========
+ODM2 Models Index
+==================
 
-.. automodule:: odm2api.ODM2.models
-   :members:
-   :undoc-members:
-   :show-inheritance:
+ODM2 is organized with a "core" schema and multiple "extension" schemas that
+extend the functionality of the core. The following sections cover some overarching concepts
+for ODM2 and then focus on specific entities within the ODM2 Core schema and ODM2's extension schemas.
+
+ODM2Core Entities
+------------------
+
+The following are entities in the `ODM2 Core Schema <http://odm2.github.io/ODM2/schemas/ODM2_Current/diagrams/ODM2Core.html>`__:
+
+.. autosummary::
+
+   odm2api.ODM2.models.Actions
+   odm2api.ODM2.models.DataSets
+   odm2api.ODM2.models.FeatureActions
+   odm2api.ODM2.models.Methods
+   odm2api.ODM2.models.Organizations
+   odm2api.ODM2.models.People
+   odm2api.ODM2.models.ProcessingLevels
+   odm2api.ODM2.models.RelatedActions
+   odm2api.ODM2.models.Results
+   odm2api.ODM2.models.SamplingFeatures
+   odm2api.ODM2.models.TaxonomicClassifiers
+   odm2api.ODM2.models.Units
+   odm2api.ODM2.models.Variables

docs/source/odm2models.rst

@@ -0,0 +1,7 @@
+ODM2 Models
+===========
+
+.. automodule:: odm2api.ODM2.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

odm2api/ODM2/models.py

@@ -155,15 +155,19 @@ class CVReferenceMaterialMedium(Base, CV):
 # Core
 # ################################################################################
 class People(Base):
-
+    """
+    Individuals that perform actions.
+    """
     PersonID = Column('personid', Integer, primary_key=True, nullable=False)
     PersonFirstName = Column('personfirstname', String(255), nullable=False)
     PersonMiddleName = Column('personmiddlename', String(255))
     PersonLastName = Column('personlastname', String(255), nullable=False)
 
 
 class Organizations(Base):
-
+    """
+    A group of people.
+    """
     OrganizationID = Column('organizationid', Integer, primary_key=True, nullable=False)
     OrganizationTypeCV = Column('organizationtypecv', ForeignKey(CVOrganizationType.Name), nullable=False,
                                 index=True)
@@ -194,7 +198,9 @@ class Affiliations(Base):
 
 
 class Methods(Base):
-
+    """
+    The procedure used to perform an action.
+    """
     MethodID = Column('methodid', Integer, primary_key=True, nullable=False)
     MethodTypeCV = Column('methodtypecv', ForeignKey(CVMethodType.Name), nullable=False, index=True)
     MethodCode = Column('methodcode', String(50), nullable=False)
@@ -207,7 +213,9 @@ class Methods(Base):
 
 
 class Actions(Base):
-
+    """
+    Actions are performed by people and may have a result.
+    """
     ActionID = Column('actionid', Integer, primary_key=True, nullable=False)
     ActionTypeCV = Column('actiontypecv', ForeignKey(CVActionType.Name), nullable=False, index=True)
     MethodID = Column('methodid', ForeignKey(Methods.MethodID), nullable=False)
@@ -234,19 +242,42 @@ class ActionBy(Base):
 
 
 class SamplingFeatures(Base):
-
+    """
+    Where or on what an action was performed.
+    """
     SamplingFeatureID = Column('samplingfeatureid', Integer, primary_key=True, nullable=False)
+    """int: Primary key identifier."""
     SamplingFeatureUUID = Column('samplingfeatureuuid', String(36), nullable=False)
+    """str: A universally unique identifier for the sampling feature."""
     SamplingFeatureTypeCV = Column('samplingfeaturetypecv', ForeignKey(CVSamplingFeatureType.Name),
                                    nullable=False, index=True)
+    """str: CV term describing the type of sampling feature."""
     SamplingFeatureCode = Column('samplingfeaturecode', String(50), nullable=False)
+    """str: A short but meaningful text identifier for the sampling feature."""
     SamplingFeatureName = Column('samplingfeaturename', String(255))
+    """str: Sampling Feature name (free text)."""
     SamplingFeatureDescription = Column('samplingfeaturedescription', String(500))
+    """str: Text describing the sampling feature."""
     SamplingFeatureGeotypeCV = Column('samplingfeaturegeotypecv', ForeignKey(CVSamplingFeatureGeoType.Name),
                                       index=True)
+    """str: Dimensionality of SamplingFeature; point2d, line2d, etc."""
     Elevation_m = Column('elevation_m', Float(53))
+    """float: The elevation of the sampling feature in meters, or in the case of Specimen, 
+              the elevation from where the SamplingFeature.Specimen was collected"""
     ElevationDatumCV = Column('elevationdatumcv', ForeignKey(CVElevationDatum.Name), index=True)
+    """str: The code for the vertical geodetic datum that specifies the zero point for 
+            the Sampling Feature Elevation"""
+    # FeatureGeometry = Column('featuregeometry',  String(50))
+    """object: The location geometry of the sampling feature on the Earth expressed using a 
+                 geometry data type. Can be a Point, Curve (profile, trajectory, etc), 
+                 Surface (flat polygons, etc) or Solid/Volume (although often limited to 
+                 2D geometries). """
+
     FeatureGeometryWKT = Column('featuregeometrywkt', String(50))
+    """str: The location geometry of the sampling feature on the Earth expressed as 
+              well known text (WKT). Can be a Point, Curve (profile, trajectory, etc.), 
+              Surface (flat polygons, etc.), or Solid/Volume (although often limited to 
+              2D geometries)."""
     __mapper_args__ = {
         'polymorphic_on': case(
             [
@@ -259,7 +290,10 @@ class SamplingFeatures(Base):
 
 
 class FeatureActions(Base):
-
+    """
+    Provides flexible linkage between Actions and the SamplingFeatures
+    on which or at which they were performed.
+    """
     FeatureActionID = Column('featureactionid', Integer, primary_key=True, nullable=False)
     SamplingFeatureID = Column('samplingfeatureid', ForeignKey(SamplingFeatures.SamplingFeatureID),
                                nullable=False)
@@ -270,7 +304,9 @@ class FeatureActions(Base):
 
 
 class DataSets(Base):
-
+    """
+    Enables grouping of results into a larger dataset.
+    """
     DataSetID = Column('datasetid', Integer, primary_key=True, nullable=False)
 
     # This has been changed to String to support multiple database uuid types
@@ -282,15 +318,19 @@ class DataSets(Base):
 
 
 class ProcessingLevels(Base):
-
+    """
+    Levels to which data have been quality controlled.
+    """
     ProcessingLevelID = Column('processinglevelid', Integer, primary_key=True, nullable=False)
     ProcessingLevelCode = Column('processinglevelcode', String(50), nullable=False)
     Definition = Column('definition', String(500))
     Explanation = Column('explanation', String(500))
 
 
 class RelatedActions(Base):
-
+    """
+    Enables specifying relationships among Actions (e.g., workflows, etc.)
+    """
     RelationID = Column('relationid', Integer, primary_key=True, nullable=False)
     ActionID = Column('actionid', ForeignKey(Actions.ActionID), nullable=False)
     RelationshipTypeCV = Column('relationshiptypecv', ForeignKey(CVRelationshipType.Name), nullable=False,
@@ -302,7 +342,9 @@ class RelatedActions(Base):
 
 
 class TaxonomicClassifiers(Base):
-
+    """
+    Terms for classifying results.
+    """
     TaxonomicClassifierID = Column('taxonomicclassifierid', Integer, primary_key=True, nullable=False)
     TaxonomicClassifierTypeCV = Column(
         'taxonomicclassifiertypecv',
@@ -321,7 +363,9 @@ class TaxonomicClassifiers(Base):
 
 
 class Units(Base):
-
+    """
+    Units of measure.
+    """
     UnitsID = Column('unitsid', Integer, primary_key=True, nullable=False)
     UnitsTypeCV = Column('unitstypecv', ForeignKey(CVUnitsType.Name), nullable=False, index=True)
     UnitsAbbreviation = Column('unitsabbreviation', String(255), nullable=False)
@@ -330,7 +374,9 @@ class Units(Base):
 
 
 class Variables(Base):
-
+    """
+    What was observed.
+    """
     VariableID = Column('variableid', Integer, primary_key=True, nullable=False)
     VariableTypeCV = Column('variabletypecv', ForeignKey(CVVariableType.Name), nullable=False, index=True)
     VariableCode = Column('variablecode', String(50), nullable=False)
@@ -341,7 +387,9 @@ class Variables(Base):
 
 
 class Results(Base):
-
+    """
+    The result of an action.
+    """
     ResultID = Column('resultid', BigIntegerType, primary_key=True)
 
     # This has been changed to String to support multiple database uuid types

odm2api/ODM2/services/readService.py

@@ -373,16 +373,34 @@ def getProcessingLevels(self, ids=None, codes=None):
 
     # Sampling Feature
     def getSamplingFeatures(self, ids=None, codes=None, uuids=None, type=None, wkt=None, results=False):
-        """
-        * Pass nothing - returns a list of all sampling feature objects with
-          each object of type specific to that sampling feature
-        * Pass a list of SamplingFeatureID - returns a single sampling feature object for the given ids
-        * Pass a list of SamplingFeatureCode - returns a single sampling feature object for the given code
-        * Pass a list of SamplingFeatureUUID - returns a single sampling feature object for the given UUID's
-        * Pass a SamplingFeatureType - returns a list of sampling feature objects of the type passed in
-        * Pass a SamplingFeature Well Known Text - return a list of sampling feature objects
-        * Pass whether or not you want to return only the sampling features
-          that have results associated with them
+        """Retrieve a list of Sampling Feature objects.
+
+        If no arguments are passed to the function, or their values are None,
+        all Sampling Feature objects in the database will be returned.
+
+        Args:
+            ids (list, optional): List of SamplingFeatureIDs.
+            codes (list, optional): List of SamplingFeature Codes.
+            uuids (list, optional): List of UUIDs string.
+            type (str, optional): Type of Sampling Feature from
+                `controlled vocabulary name <http://vocabulary.odm2.org/samplingfeaturetype/>`_.
+            wkt (str, optional): SamplingFeature Well Known Text.
+            results (bool, optional): Whether or not you want to return only the
+                sampling features that have results associated with them.
+
+        Returns:
+            list: List of Sampling Feature objects
+
+        Examples:
+            >>> READ = ReadODM2(SESSION_FACTORY)
+            >>> READ.getSamplingFeatures(ids=[39, 40])
+            >>> READ.getSamplingFeatures(codes=['HOME', 'FIELD'])
+            >>> READ.getSamplingFeatures(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
+            ...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
+            >>> READ.getSamplingFeatures(type='Site')
+            >>> READ.getSamplingFeatures(wkt='POINT (30 10)')
+            >>> READ.getSamplingFeatures(results=True)
+            >>> READ.getSamplingFeatures(type='Site', results=True)
 
         """
         if results: