Add sphinx documentation of API functionality

ce/api/data.py

@@ -20,22 +20,28 @@ def data(sesh, model, emission, time, area, variable, timescale='other',
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         model (str): Short name for some climate model (e.g "CGCM3")
-        emission (str): Short name for some emission scenario (e.g.
-            "historical+rcp85")
+
+        emission (str): Short name for some emission scenario
+            (e.g."historical+rcp85")
+
         time (int): Timestep index (0-based) representing the time of year;
             0-11 for monthly, 0-3 for seasonal, 0 for annual datasets.
+
         area (str): WKT polygon of selected area
+
         variable (str): Short name of the variable to be returned
+
         timescale (str): Description of the resolution of time to be
             returned (e.g. "monthly" or "yearly")
+
         ensemble_name (str): Name of ensemble
 
     Returns:
         dict:
-
-        Empty dictionary if there exist no files matching the provided
-        model and emissions scenario.
+            Empty dictionary if there exist no files matching the provided
+            model and emissions scenario.
 
         Otherwise returns a single dict keyed on the run id for all
         runs that match the model and emissions scenario. values are a

ce/api/grid.py

@@ -25,10 +25,11 @@ def grid(sesh, id_):
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         id_ (str): Unique id which is a key to the data file requested
 
     Returns:
-        dict: Empty dictionary if model_id is not found in the database.
+        dict: Empty dictionary if id_ is not found in the database.
 
         Otherwise, returns a single dict with the key of the file's
         unique_id and the value consisting of a nested dictionary with

ce/api/lister.py

@@ -8,14 +8,17 @@ def lister(sesh, ensemble_name='ce_files', model=None):
     '''
     Args
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         ensemble (str): Some named ensemble
+
         model (str): Short name for some climate model (e.g "CGCM3")
 
     Returns:
         list of all unique_ids within that ensemble and/or model.
 
-        For example:
-            ensemble = default, model = PRISM (assuming PRISM group is in 'ce' ensemble)
+        For example, given ensemble = default, model = PRISM
+        (assuming PRISM files are in 'ce_files' ensemble)::
+
             [
                 tmax_monClim_PRISM_historical_run1_198101-201012,
                 tmin_monClim_PRISM_historical_run1_198101-201012,

ce/api/metadata.py

@@ -18,6 +18,7 @@ def metadata(sesh, model_id):
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         model_id (str): Unique id which is a key to the data file requested
 
     Returns:

ce/api/models.py

@@ -9,13 +9,12 @@ def models(sesh, ensemble_name='ce_files'):
     Args
         sesh (sqlalchemy.orm.session.Session): A database Session object
 
-    Returns list of all models available:
+    Returns list of all models available::
 
-    [
-    model_short_name1,
-    model_short_name2,
-    ...
-    ]
+        [
+        model_short_name1,
+        model_short_name2,
+        ]
     '''
 
     ensemble = sesh.query(Ensemble).filter(Ensemble.name == ensemble_name).first()

ce/api/multimeta.py

@@ -23,7 +23,9 @@ def multimeta(sesh, ensemble_name='ce_files', model=''):
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         ensemble (str): Some named ensemble
+
         model (str): Short name for some climate model (e.g "CGCM3")
 
     Returns:

ce/api/multistats.py

@@ -19,18 +19,26 @@ def multistats(sesh, ensemble_name='ce_files', model='', emission='', time=0,
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         ensemble_name (str): The name of the application-level ensemble
             (e.g. "ce_files")
+
         model (str): Short name for some climate model (e.g "CGCM3") to
             be used as a filter
+
         emission (str): Short name for some emission scenario (e.g.
             "historical+rcp85") to be used as a filter
+
         time (int): Timestep index (0-based) representing the time of year;
             0-11 for monthly, 0-3 for seasonal, 0 for annual datasets.
+
         area (str): WKT polygon of selected area
+
         variable (str): Short name of the variable to be returned
+
         timescale (str): Description of the resolution of time to be
             returned (e.g. "monthly" or "yearly")
+
         cell_method (str): Statistical operation applied to variable in a
             climatological dataset (e.g "mean" or "standard_deviation").
             Defaulted to "mean".

ce/api/stats.py

@@ -31,10 +31,14 @@ def stats(sesh, id_, time, area, variable):
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         id_ (str): Unique id which is a key to the data file requested
+
         time (int): Timestep index (0-based) representing the time of year;
             0-11 for monthly, 0-3 for seasonal, 0 for annual datasets.
+
         area (str): WKT polygon of selected area
+
         variable (str): Short name of the variable to be returned
 
     Returns:

ce/api/streamflow/watershed.py

@@ -41,8 +41,16 @@ def watershed(sesh, station, ensemble_name):
     :param station: (string) Location of drainage point, WKT POINT format
     :param ensemble_name: (string) Name of the ensemble containing data files backing
         providing data for this request.
-    :return: (dict) representation for JSON response object. See function
-        `worker` for details.
+    :return: dict representation for JSON response object with the following
+        attributes:
+            area: Area of the watershed
+
+            elevation: Minimum and maximum elevations
+
+            shape: A GeoJSON object representing the outline of the watershed;
+                a concave hull of the cell rectangles.
+
+            hypsometric_curve: Elevation-area histogram of the watershed
 
     This function is primarily responsible for finding the relevant data files
     and converting their contents to `VicDataGrid` objects for consumption by
@@ -95,13 +103,7 @@ def worker(station_lonlat, flow_direction, elevation, area, hypso_params=None):
     :param flow_direction: (VicDataGrid) Flow direction grid
     :param elevation: (VicDataGrid) Elevation grid
     :param area: (VicDataGrid) Area grid
-    :return: dict representation for JSON response object with the following
-        attributes:
-            area: Area of the watershed
-            elevation: Minimum and maximum elevations
-            shape: A GeoJSON object representing the outline of the watershed;
-                a concave hull of the cell rectangles.
-            hypsometric_curve: Elevation-area histogram of the watershed
+    :return: (dict) representation for JSON response object; see watershed() for details
     """
     if hypso_params is None:
         # Default parameters cover total range of BC elevations from

ce/api/timeseries.py

@@ -16,8 +16,11 @@ def timeseries(sesh, id_, area, variable):
 
     Args:
         sesh (sqlalchemy.orm.session.Session): A database Session object
+
         id_ (str): Unique id which is a key to the data file requested
+
         area (str): WKT polygon of selected area
+
         variable (str): Short name of the variable to be returned
 
     Returns:

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/source/api/api-index.rst

@@ -0,0 +1,20 @@
+API Documentation
+=================
+
+.. mdinclude:: api-overview.md
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: The backend exposes the following API endpoints:
+
+   data <data-api>
+   grid <grid-api>
+   lister <lister-api>
+   metadata <metadata-api>
+   models <models-api>
+   multimeta <multimeta-api>
+   multistats <multistats-api>
+   stats <stats-api>
+   timeseries <timeseries-api>
+   watershed <watershed-api>

doc/source/api/api-overview.md

@@ -0,0 +1,4 @@
+Documentation for each API endpoint is automatically generated from the code and docstring for that API's main function and may not be entirely user-friendly. There are some very minor differences between arguments for each API function and the parameters needed for a web query.
+
+1. Web queries do not supply a `sesh` (database session) as an argument; that will be automatically done by the query parser.
+2. Parameters supplied in a query url should be web-encoded.

doc/source/api/data-api-usage.md

@@ -0,0 +1,5 @@
+This endpoint accepts parameters describing a collection of datasets and a time of year and extracts data for the requested time of year from all datasets that match the parameters and contain it as one or more timeseries.
+
+It shows how a variable changes over the long term. For example, with six datasets representing different climatologies it would return mean daily  August precipitation from 1961-1990, 1971-2000, 1981-2010, 2010-2039, 2040-2069, and 2070-2099 as a single timeseries.
+
+This slices the data along a different axis than the `timeseries` endpoint, which shows values of a variable within a given dataset, and would return a timeseries consisting of mean daily precipitation for January 1961-1990, February 1961-1990, etc. instead.

doc/source/api/data-api.rst

@@ -0,0 +1,13 @@
+.. To update documentation on the data endpoint, update the docstring in the
+   code or data-api-usage.md.
+
+
+data
+====
+.. mdinclude:: data-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+------
+
+.. autofunction:: ce.api.data

doc/source/api/grid-api-usage.md

@@ -0,0 +1,3 @@
+This endpoint is not currently used by the PCEX frontend. It was originally intended to provide information needed for a user to select a polygon of interest on a map; this functionality is now handled by queries to the ncWMS map server. 
+
+This endpoint may be of use for systems that want to designate spatial areas of especial interest but are not using ncWMS.

doc/source/api/grid-api.rst

@@ -0,0 +1,13 @@
+.. To update documentation on the grid endpoint, update the docstring in the
+   code, or grid-api-usage.md.
+
+
+grid
+====
+.. mdinclude:: grid-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+------
+
+.. autofunction:: ce.api.grid

doc/source/api/lister-api-usage.md

@@ -0,0 +1,3 @@
+This endpoint returns a list of unique identification strings corresponding to all available datafiles. 
+
+It is not currently used by the PCEX frontend; it has been superceded by the `multimeta` endpoint. Like `lister`, `multimeta` returns a list of `unique_id` strings associated with all available files in an ensemble, but `multimeta` additionally returns metadata attributes describing the contents of each file. For most applications, it is probably more efficient to call `multimeta` than to call `lister` and then make a seperate query to get metadata describing each individual dataset to determine which ones are of interest.

doc/source/api/lister-api.rst

@@ -0,0 +1,13 @@
+.. To update documentation on the lister endpoint, update the docstring in the
+   code or lister-api-usage.md.
+
+
+lister
+======
+.. mdinclude:: lister-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+------
+
+.. autofunction:: ce.api.lister

doc/source/api/metadata-api-usage.md

@@ -0,0 +1 @@
+This endpoint returns detailed metadata on a single file. In addition to returning attributes describing the data in the file, it returns a list of all timestamps available within the file. This allows a user to request a map image from the map server corresponding to a specific timestamp.

doc/source/api/metadata-api.rst

@@ -0,0 +1,25 @@
+.. Documentation on metadata endpoint is split over three locations: the function's docstring,
+   metadata-api-usage.md, which explains the general usage of the endpoint, and this file, which
+   takes advantage of the sphinx RST "warning" functionality to post a warning about parameter names.
+
+metadata
+========
+.. mdinclude:: metadata-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+.. warning::
+     Parameter names for this endpoint are not consistent with parameter names for the other
+     endpoints. Every other endpoint uses the word "model" to refer to the global climate
+     model (GCM) that produced a particular dataset.
+
+     This endpoint uses the "model_id" parameter to reger to a dataset's unique identification
+     string, which is called "id_" in every other endpoint.
+
+     This is a holdover from a much older data design when all data from each model was
+     in a single file.
+
+
+------
+
+.. autofunction:: ce.api.metadata

doc/source/api/models-api-usage.md

@@ -0,0 +1,3 @@
+This endpoint returns a list of all models in a given ensemble. "Model" in this case usually means the Global Climate Model or Regional Climate Model that simulated the data in the dataset, though in some circumstances it may refer to a different type of model, such as an interpolation algorithm used to grid observational data or elevation data. 
+
+In PCEX, it has been superceded by the `multimeta` query, which returns a list of all datasets, with attributes describing the contents of each dataset, including the model. It's usually more convenient to just collect all the available models from the list of all available datasets.

doc/source/api/models-api.rst

@@ -0,0 +1,13 @@
+.. To update documentation on the models endpoint, update the docstring in the
+   code, or models-api-usage.md.
+
+
+models
+======
+.. mdinclude:: models-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+------
+
+.. autofunction:: ce.api.models

doc/source/api/multimeta-api-usage.md

@@ -0,0 +1,16 @@
+This API endpoint provides a list of all the datasets available in a given ensemble. Datasets are identified with a unique identification string. Additional metadata describing the contents of each dataset is provided.
+
+This endpoint is intended to provide an overview of all available datasets to enable a caller to decide which datasets are of further interest for numerical data or mapping. It does not return detailed temporal metadata or any spatial metadata; see the `grid` and `metadata` endpoints for more detailed metadata about temporal or spatial extent of a dataset.
+
+## Metadata attributes
+* `institution`: The research institution that created this dataset
+* `model_id`: A short abbreviation for the General Circulation Model, Regional Climate Model, or interpolation algorithm that output this dataset
+* `model_name`: The full name of the model that created this dataset
+* `experiment`: The emissions scenario used to model this data. Emissions scenarios represent a range of possible future projections for greenhouse gas concentration in the atmosphere, typically one of the Representative Concentration Pathways (RCP). May be "historical" for datasets based on historical data
+* `variables`: A list of variables in this dataset, with name and a short description. Variables are the numerical quantities being measured or projected, such as maximum temperature, precipitation, or derived indices.
+* `ensemble_member`: A model may be run multiple times with different initialization conditions; data from these runs is distinguished by the ensemble_member attribute
+* `timescale`: The temporal resolution of the data. `monthly`, `seasonal`, or `yearly`
+* `multi_year_mean`: Whether or not this datafile is a climatological mean. Climatological means 
+* `start_date`: The start of the temporal interval described by this dataset 
+* `end_date`: The end of the temporal interval described by this dataset
+* `modtime`: The most recent data this dataset was updated. Useful for determining whether to cache data.

doc/source/api/multimeta-api.rst

@@ -0,0 +1,13 @@
+.. To update documentation on the multimeta endpoint, update the docstring in the
+   code, or multimeta-api-usage.md.
+
+
+multimeta
+=========
+.. mdinclude:: multimeta-api-usage.md
+
+.. mdinclude:: sesh-not-needed.md
+
+------
+
+.. autofunction:: ce.api.multimeta

doc/source/api/multistats-api-usage.md

@@ -0,0 +1 @@
+This endpoint is similar to the `stats` endpoint, but instead of accepting a unique identification string and returning statistics for a timestamp in a single file, it accepts metadata parameters and returns statistics for the selected timestamp from all files that meet those parameters and contain the selected timestamp, organized by the unique ID string. This supports applications that display how statistical measures of a variable change over time or between simulated runs.