Improving documentation

Addressing issue #41

cotede/__init__.py

@@ -5,3 +5,4 @@
 __version__ = '0.21.0'
 
 from cotede import qc
+from cotede.qc import ProfileQC, ProfileQCed

cotede/qc.py

@@ -20,24 +20,40 @@
 
 
 class ProfileQC(object):
-    """ Quality Control of a CTD profile
+    """Quality Control a CTD profile
     """
+
     def __init__(self, input, cfg=None, saveauxiliary=True, verbose=True,
-            attributes=None, logger=None):
-        """
-            Input: dictionary with data.
-                - pressure[\d]:
-                - temperature[\d]:
-                - salinity[\d]:
-
-            cfg: Check cotede.utils.load_cfg() for the possible input formats
-                   for cfg.
-
-            =======================
-            - Must have a log system
-            - Probably accept incomplete cfg. If some threshold is
-                not defined, take the default value.
-            - Is the best return another dictionary?
+            attributes=None):
+        """A procedure to QC a hydrographic profile
+
+        Parameters
+        ----------
+        input: dict-like
+            An object with the data to be evaluated that responds like a
+            dictionary. For instance, a variable pressure should be acessible
+            as input['pressure'], or temperature as input['temperature'].
+            This input object could have attrs, with global attributes for
+            the whole dataset. For instance, input.attrs['lat'] would give the
+            nominal latitude of the dataset input.
+
+        cfg: dict-like or str
+            The QC configuration to be used in the current profile. If a
+            string, it should be the name of a JSON QC configuration. Check
+            the manual for the available options.
+
+        saveauxiliary: bool
+            Save features as .features
+
+        verbose: bool
+            Show extra information
+
+        attributes: dict-like, optional
+            If given, append/overwirte the input.attrs
+
+        Methods
+        -------
+        keys(self): List of input contents
         """
         # self.logger = logging.getLogger(logger or 'cotede.ProfileQC')
 

cotede/utils/__init__.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python
 
 from .utils import *
+from .utils import cotederc
 from cotede.utils.profilescollection import ProfilesQCCollection
 from cotede.utils.profilescollection import ProfilesQCPandasCollection
-from .config import load_cfg
+from .config import load_cfg, list_cfgs
 
 import logging

cotede/utils/config.py

@@ -1,3 +1,8 @@
+# -*- coding: utf-8 -*-
+
+"""Resources related to QC configuration
+"""
+
 from collections import OrderedDict
 import copy
 import json
@@ -14,6 +19,10 @@ def list_cfgs():
     used, can be saved to be re-used later. Several procedures are built-in
     CoTeDe, but the user can create its own collection. This function returns
     a list of all procedures available, built-in + the local user collection.
+
+    See also
+    --------
+    utils.load_cfg
     """
     cfg = pkg_resources.resource_listdir('cotede', "qc_cfg")
     cfg = sorted([c[:-5] for c in cfg if c[-5:] == ".json"])
@@ -39,29 +48,49 @@ def inheritance(child, parent):
 
 
 def load_cfg(cfgname="cotede"):
-    """ Load the QC configurations
-
-        The possible inputs are:
-            - None: Will use the CoTeDe's default configuration
-
-            - Config name [string]: A string with the name of a json file
-                describing the QC procedure. It will first search among
-                the build in pre-set (cotede, eurogoos, gtspp or argo),
-                otherwise it will search in ~/.cotederc/cfg
-
-            - User configs [dict]: a dictionary composed by the variables
-                to be evaluated as keys, and inside it another dictionary
-                with the tests to perform as keys. example
-                {'main':{
-                    'valid_datetime': None,
-                    },
-                'temperature':{
-                    'global_range':{
-                        'minval': -2.5,
-                        'maxval': 45,
-                        },
-                    },
-                }
+    """Load a QC configuration
+
+    A QC procedure is a sequence of tests, and respective tuning parameters
+    used to quality control a dataset. This is how the user controls the
+    QC steps to apply.
+
+    Parameters
+    ----------
+    cfgname : string or dict-list, optional
+
+        - None: If not given, it will use the CoTeDe's default configuration,
+          which is equivalent to use cfgname='cotede'.
+
+        - A config name [string]: A string with the name of a json file
+          describing the QC procedure. It will first search among the build
+          in pre-set (ex.: cotede, eurogoos, gtspp, argo, ...). If can't find
+          a config with that name, it will search at ~/.config/cotederc/cfg/,
+          or the path defined by the local variable $COTEDE_DIR.
+
+        - Inline config [dict-like]: A dictionary describing the variables to
+          process and which tests to use on each one. A minimalist example to
+          apply the gradient test in the sea water temperature could be:
+
+              >>> {"sea_water_temperature": {"gradient": 3}}
+
+        If inherit is used, it should be a string or a list of other
+        procedures to inherit, where each item has higher priority than the
+        following ones. For example:
+
+        >>> {"inherit": "eurogoos", "sea_water_temperature": {"gradient": 2}}
+
+        will use all the setup from eurogoos, and include/overwrite the
+        gradient test for sea_water_temperature with a threshold of 2.
+
+    Returns
+    -------
+    cfg : OrderedDict
+        A dictionary defining a full QC procedure that defines which tests to
+        run on which variables.
+
+    See also
+    --------
+    utils.list_cfgs
     """
     if cfgname is None:
         cfgname = "cotede"

cotede/utils/utils.py

@@ -1,5 +1,10 @@
 # -*- coding: utf-8 -*-
 
+"""Utilities for CoTeDe
+
+Miscelaneous resources to support CoTeDe.
+"""
+
 import os
 from os.path import expanduser
 import re
@@ -8,7 +13,43 @@
 
 
 def cotederc(subdir=None):
-    """Returns the directory with custom config for CoTeDe
+    """Directory with custom configuration for CoTeDe
+
+    To keep the local environment tight, CoTeDe expects to find all local files,
+    like pre-set QC procedures, in one single place. This function returns the
+    path to that directory.
+
+    Parameters
+    ----------
+    subdir : str, optional
+        Sub-directory inside the base custom directory.
+
+    Returns
+    -------
+    str
+        A path to the local custom files.
+
+        The default path is a directory at the user's home like::
+
+            ~/.config/cotederc/
+
+    Note
+    ----
+    That default path can be modified by defining the environment variable
+    COTEDE_DIR. On bash that could be done like::
+
+        export COTEDE_DIR='/my/other/awesome/path/'
+
+    Note
+    ----
+    For windows users the path is automatically adjusted to reflect its
+    syntax.
+
+    Example
+    -------
+    A sub-directory for configuration files, named 'cfg', can be determined by::
+
+    >>> cotederc('cfg')
     """
     path = os.getenv("COTEDE_DIR", os.path.join("~", ".config", "cotederc"))
     path = os.path.expanduser(path)

docs/environment.yml

@@ -9,3 +9,4 @@ dependencies:
 - pip
 - pip:
     - oceansdb>=0.8.6
+    - cotede

docs/source/api.rst

@@ -0,0 +1,27 @@
+.. currentmodule:: cotede
+
+#############
+API reference
+#############
+
+The public API resources are listed below.
+All the rest of CoTeDe is considered support infrastructure and there is no reason to use or access explicitly what is not shown here.
+I do intend to expand these resources in the near future, but this is what is available now.
+
+Top-level resources
+===================
+
+.. autosummary::
+   :toctree: generated/
+
+   ProfileQC
+
+Utils
+=====
+
+.. autosummary::
+   :toctree: generated/
+
+   utils.cotederc
+   utils.list_cfgs
+   utils.load_cfg

docs/source/conf.py

@@ -12,14 +12,17 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
+from datetime import datetime
 import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # 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.
 #sys.path.insert(0, os.path.abspath('.'))
 
+import cotede
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -29,10 +32,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.imgmath'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.imgmath",
+    "sphinx.ext.napoleon",
 ]
 
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -47,16 +55,16 @@
 
 # General information about the project.
 project = u'CoTeDe'
-copyright = u'2015, Guilherme Castelão'
+copyright = "2006-{}, Guilherme Castelão".format(datetime.now().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.21'
+version = ".".join(cotede.__version__.split(".")[:2])
 # The full version, including alpha/beta/rc tags.
-release = '0.21.0'
+release = cotede.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/generated/cotede.ProfileQC.rst

@@ -0,0 +1,25 @@
+cotede.ProfileQC
+================
+
+.. currentmodule:: cotede
+
+.. autoclass:: ProfileQC
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ProfileQC.__init__
+      ~ProfileQC.keys
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ProfileQC.attrs
+      ~ProfileQC.features