api docs with fixes to some docstrings and imports

cosima_cookbook/date_utils.py

@@ -1,13 +1,10 @@
-
-#!/usr/bin/env python
-
 """
 Copyright 2018 ARC Centre of Excellence for Climate Systems Science
 author: Aidan Heerdegen <[email protected]>
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -189,4 +186,4 @@ def shift_time(ds):
     """
     Apply time shift to un-decoded time axis, to align datasets and 
     """
-    pass
+    pass

cosima_cookbook/diagnostics/mean_tau_x.py

@@ -1,5 +1,5 @@
 from ..memory import memory
-from ..netcdf_index import get_nc_variable
+from ..querying import getvar
 
 @memory.cache
 def mean_tau_x(expt):

cosima_cookbook/diagnostics/overturning.py

@@ -1,4 +1,4 @@
-from ..netcdf_index import get_nc_variable, get_variables
+from ..querying import getvar, get_variables
 from ..memory import memory
 
 @memory.cache

cosima_cookbook/diagnostics/simple.py

@@ -1,4 +1,4 @@
-from ..netcdf_index import get_nc_variable, get_variables
+from ..querying import getvar, get_variables
 from ..memory import memory
 
 import logging

cosima_cookbook/netcdf_index.py

@@ -2,12 +2,9 @@
 Common tools for accessing NetCDF4 variables
 """
 
-print('netcdf_index loaded.')
-
 __all__ = ['build_index', ]
 
 import netCDF4
-import dataset
 import re
 import os
 import sys

cosima_cookbook/querying.py

@@ -1,12 +1,15 @@
+"""querying.py
+
+Functions for data discovery.
+
+"""
+
 import logging
 import os.path
 import pandas as pd
 from sqlalchemy import func, distinct
-
 import xarray as xr
-
 from . import database
-
 from .database import NCExperiment, NCFile, CFVariable, NCVar
 
 class VariableNotFoundError(Exception):
@@ -92,26 +95,37 @@ def getvar(expt, variable, session, ncfile=None, n=None,
     """For a given experiment, return an xarray DataArray containing the
     specified variable.
     
-    expt - text string indicating the name of the experiment
-    variable - text string indicating the name of the variable to load
-    session - a database session created by cc.database.create_session()
-
-    ncfile - If disambiguation based on filename is required, pass the ncfile
-    argument.
-    n - A subset of output data can be obtained by restricting the number of 
+    Parameters
+    ----------
+    expt : str
+        text string indicating the name of the experiment
+    variable : str
+        text string indicating the name of the variable to load
+    session : 
+        a database session created by cc.database.create_session()
+    ncfile
+        If disambiguation based on filename is required, pass the ncfile argument.
+    n
+        A subset of output data can be obtained by restricting the number of 
         netcdf files to load (use a negative value of n to get the last n 
         files, or a positive n to get the first n files).
-    start_time - Only load data after this date. Specify the date as a text string
+    start_time 
+        Only load data after this date. Specify the date as a text string
         (e.g. '1900-1-1')
-    start_time - Only load data before this date. Specify the date as a text string
+    start_time
+        Only load data before this date. Specify the date as a text string
         (e.g. '1900-1-1')
-    chunks - Override any chunking by passing a chunks dictionary.
-    offset - A time offset (in an integer number of days) can also be applied.
-    decode_times - Time decoding can be disabled by passing decode_times=False
-    check_present - indicates whether to check the presence of the file before 
+    chunks
+        Override any chunking by passing a chunks dictionary.
+    offset
+        A time offset (in an integer number of days) can also be applied.
+    decode_times
+        Time decoding can be disabled by passing decode_times=False
+    check_present
+        indicates whether to check the presence of the file before 
         loading.
-    """
 
+    """
     f, v = database.NCFile, database.NCVar
     q = (session
          .query(f, v)

cosima_cookbook/summary/nml_diff.py

@@ -55,13 +55,17 @@ def superset(nmlall):
 def nmldiff(nmlall):
     """Remove every group/group member that is the same in all file Namelists.
 
-    Input: dict (e.g. returned by nmldict) with key:value pairs where
-            key is filename path string
-            value is complete Namelist from filename
-    Output: modified input dict with key:value pairs where
-            key is filename strings
-            value is Namelist from filename, with any group/group member
-                common to all other files removed
+    Parameter
+    ---------
+    Input : dict 
+        (e.g. returned by nmldict) with key:value pairs where
+        key is filename path string
+        value is complete Namelist from filename
+    Output : dict
+        modified input dict with key:value pairs where
+        key is filename strings
+        value is Namelist from filename, with any group/group member
+        common to all other files removed
     """
 
 # Create diff by removing common groups/members from nmlall.

docs/source/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
-sys.path.insert(0, os.path.abspath('../../cosima-cookbook'))
+#import os
+#import sys
+#sys.path.insert(0, os.path.abspath('../../cosima-cookbook'))
 
 
 # -- Project information -----------------------------------------------------
@@ -30,9 +30,15 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
+extensions = [ 
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
 ]
 
+napoleon_google_docstring = False
+napoleon_use_param = False
+napoleon_use_ivar = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/source/cosima_cookbook.diagnostics.rst

@@ -0,0 +1,38 @@
+cosima\_cookbook.diagnostics package
+====================================
+
+Submodules
+----------
+
+cosima\_cookbook.diagnostics.mean\_tau\_x module
+------------------------------------------------
+
+.. automodule:: cosima_cookbook.diagnostics.mean_tau_x
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.diagnostics.overturning module
+-----------------------------------------------
+
+.. automodule:: cosima_cookbook.diagnostics.overturning
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.diagnostics.simple module
+------------------------------------------
+
+.. automodule:: cosima_cookbook.diagnostics.simple
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: cosima_cookbook.diagnostics
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/cosima_cookbook.plots.rst

@@ -0,0 +1,46 @@
+cosima\_cookbook.plots package
+==============================
+
+Submodules
+----------
+
+cosima\_cookbook.plots.lineplots module
+---------------------------------------
+
+.. automodule:: cosima_cookbook.plots.lineplots
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.plots.maps module
+----------------------------------
+
+.. automodule:: cosima_cookbook.plots.maps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.plots.overturning module
+-----------------------------------------
+
+.. automodule:: cosima_cookbook.plots.overturning
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.plots.scalar module
+------------------------------------
+
+.. automodule:: cosima_cookbook.plots.scalar
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: cosima_cookbook.plots
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/cosima_cookbook.rst

@@ -0,0 +1,87 @@
+cosima\_cookbook package
+========================
+
+Subpackages
+-----------
+
+.. toctree::
+
+   cosima_cookbook.diagnostics
+   cosima_cookbook.plots
+   cosima_cookbook.summary
+
+Submodules
+----------
+
+cosima\_cookbook.database module
+--------------------------------
+
+.. automodule:: cosima_cookbook.database
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.database\_utils module
+---------------------------------------
+
+.. automodule:: cosima_cookbook.database_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.date\_utils module
+-----------------------------------
+
+.. automodule:: cosima_cookbook.date_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.distributed module
+-----------------------------------
+
+.. automodule:: cosima_cookbook.distributed
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.memory module
+------------------------------
+
+.. automodule:: cosima_cookbook.memory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.netcdf\_index module
+-------------------------------------
+
+.. automodule:: cosima_cookbook.netcdf_index
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.netcdf\_utils module
+-------------------------------------
+
+.. automodule:: cosima_cookbook.netcdf_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.querying module
+--------------------------------
+
+.. automodule:: cosima_cookbook.querying
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: cosima_cookbook
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/cosima_cookbook.summary.rst

@@ -0,0 +1,30 @@
+cosima\_cookbook.summary package
+================================
+
+Submodules
+----------
+
+cosima\_cookbook.summary.nml\_diff module
+-----------------------------------------
+
+.. automodule:: cosima_cookbook.summary.nml_diff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cosima\_cookbook.summary.nml\_summary module
+--------------------------------------------
+
+.. automodule:: cosima_cookbook.summary.nml_summary
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: cosima_cookbook.summary
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -26,6 +26,7 @@ of diagnostics for models run by members of the community.
 
     getting_started
     related_projects
+    modules
 
 Indices and tables
 ==================