Merge branch 'develop' into feature/gpm

README.MD

@@ -24,7 +24,7 @@ For installation instructions, see [install.md](doc/source/install.md).
 
 A full Windows 10 Installation of PODPAC can be downloaded from [here](https://s3.amazonaws.com/podpac-s3/releases/PODPAC_latest_install_windows10.zip). To use it, extract the zip file in a folder on your machine.
 
-For older versions, substitute `latest` in the url with the version number. For example, version `0.2.0` can be downloaded using this url [https://s3.amazonaws.com/podpac-s3/releases/PODPAC_0.2.0_install_windows10.zip](https://s3.amazonaws.com/podpac-s3/releases/PODPAC_0.2.0_install_windows10.zip)
+For older versions, substitute `latest` in the url with the version number. For example, version `0.2.1` can be downloaded using this url [https://s3.amazonaws.com/podpac-s3/releases/PODPAC_0.2.1_install_windows10.zip](https://s3.amazonaws.com/podpac-s3/releases/PODPAC_0.2.1_install_windows10.zip)
 
 ## Documentation
 
@@ -52,6 +52,9 @@ We are working towards stability so that the above would no longer be true, and
 
 As such use PODPAC at your own risk. 
 
+## Acknowledgments
+
+This material is based upon work supported by NASA under Contract No 80NSSC18C0061.
 
 ## References
 

doc/source/_templates/attribute.rst

@@ -0,0 +1,7 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoattribute:: {{objname}}
+   :annotation:
+

doc/source/_templates/base.rst

@@ -0,0 +1,6 @@
+
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+

doc/source/_templates/class.rst

@@ -0,0 +1,62 @@
+{{ fullname | escape | underline}}
+
+{% set exclude_methods = ['add_traits', 'class_own_trait_events', 'class_own_traits', 'class_trait_names', 'class_traits',
+                          'has_trait', 'hold_trait_notifications', 'notify_change', 'observe', 'on_trait_change',
+                          'set_trait', 'setup_instance', 'trait_events', 'trait_metadata', 'trait_names', 'traits',
+                          'unobserve', 'unobserve_all'] %}
+
+{% set exclude_attributes = ['cross_validation_lock'] %}
+
+{% set _constructors = ['from_json', 'from_xarray', 'from_definition', 'points', 'grid'] %}
+
+{% if methods %}
+{% set constructors = methods|select('in', _constructors)|list %}
+{% set methods = methods|reject('in', exclude_methods)|reject('in', constructors) %}
+{% endif %}
+
+{% if attributes %}
+{% set attributes = attributes|reject('in', exclude_attributes) %}
+{% endif %}
+
+.. currentmodule:: {{ module }}
+
+
+.. autoclass:: {{ objname }}
+
+   {% block constructors %}
+
+   {% if constructors %}
+   .. rubric:: Alternative Constructors
+
+   .. autosummary::
+   {% for item in constructors %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   :members:
+   .. automethod:: __init__

doc/source/_templates/function.rst

@@ -0,0 +1,6 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{objname}}
+

doc/source/_templates/method.rst

@@ -0,0 +1,8 @@
+
+
+{{ fullname | escape | underline}}
+
+METHOD
+
+.. currentmodule:: {{ module }}
+

doc/source/_templates/module.rst

@@ -0,0 +1,38 @@
+
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+

doc/source/conf.py

@@ -37,17 +37,15 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+needs_sphinx = '1.8'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
-    # 'sphinx.ext.napoleon',  # prefer numpydoc
-    'numpydoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
@@ -100,23 +98,21 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# see https://numpydoc.readthedocs.io/en/latest/install.html
-numpydoc_class_members_toctree = True
-numpydoc_show_class_members = False
-numpydoc_show_inherited_class_members = False
-
 # generate autosummary files into the :toctree: directory
-# see http://www.sphinx-doc.org/en/master/ext/autosummary.html
+#   See http://www.sphinx-doc.org/en/master/ext/autosummary.html
+# unfortunately this inherits all members of a class and no parameters below will help
+#   See https://github.com/sphinx-doc/sphinx/pull/4029
+# Chose to use templates in the _templates directory to override this
 autosummary_generate = True
 
 # autodoc options
 autoclass_content = 'class'  # only include docstring from Class (not __init__ method)
 autodoc_inherit_docstrings = False
 autodoc_default_options = {
     'members': None, # means yes/true/on
-    'undoc-members': None
+    'undoc-members': None,
+    'show-inheritance': None
 }
-# # autodoc_default_flags = ['members']  # deprecated in sphinx 1.8
 
 # shortened external links. see http://www.sphinx-doc.org/en/master/ext/extlinks.html
 extlinks = {'issue': ('{0}/issues/%s'.format(GIT_URL), '#'), # refer to issues :issue:`123`

doc/source/developer/contributing.md

@@ -49,25 +49,64 @@ Examples:
 - https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html
 - https://docs.scipy.org/doc/numpy/docs/howto_document.html#example-source
 
-Note that class attributes can be documented multiple ways. 
-We choose to document attributes in the main class docs:
+Note that class attributes can be documented multiple ways.
+ - Public attributes (traits) should be documented in the preceding line with `#: <type> : <description>.`
+ - Public properties created with the `@property` decorator should be documented in the getter method.
+ - Additionaly, document key public attributes and properties again in the main class docs under `Parameters`.
 
 ```python
-class ExampleClass(object):
+class ExampleClass(tl.HasTraits):
     """The summary line for a class docstring should fit on one line.
 
-    Properties created with the ``@property`` decorator should be documented
-    in the property's getter method and left out of here.
+    Additional details should be documented here.
 
-    Attributes
+    Parameters
     ----------
     attr1 : str
-        Description of `attr1`.
+        Description of attr1.
     attr2 : dict, optional
-        Description of `attr2`.
+        Description of attr2.
+    """
+
+    #: str : Description of attr1
+    attr1 = tl.Str()
+
+    #: dict : Description of attr2
+    attr2 = tl.Dict(allow_none=True)
+
+    #: int : Description of secondary attr3
+    attr3 : tl.Int()
+
+    @property
+    def attr4(self):
+        """:bool: Description of attr4."""
+
+        return True
+```
+
+The docstrings for inherited traits are not inherited. You must define inherited traits again in child classes:
+
+```python
+class ExampleChild(ExampleClass):
+    """Summary.
 
     ...
     """
+
+    #: str : Description of my_attr (not inherited)
+    my_attr = tl.Str()
+
+    # inherited traits, duplicated here for the docstrings:
+
+    #: str : Description of attr1
+    attr1 = tl.Str()
+
+    #: dict : Description of attr2
+    attr2 = tl.Dict(allow_none=True)
+
+    #: int : Description of secondary attr3
+    attr3 : tl.Int()
+
 ```
 
 #### References
@@ -105,6 +144,51 @@ $ pylint podpac/settings.py     # lint single file
 
 Configuration options are specified in `.pylintrc`.
 
+## Logging
+
+We use the python `logging` library to support library logging.
+To include logging in your module, use:
+
+```python
+import logging
+log = logging.getLogger(__name__)  # creates a logger with the current module name
+
+# log a message
+log.debug('Debug message')
+log.info('Info message')
+log.warning('Warning message')
+log.error('Error message')
+```
+
+Do not set levels, handlers, or formatters in your modules.
+See the [python logging documentation](https://docs.python.org/3/library/logging.html#logging.Logger.debug) for details on how to construct log messages.
+
+To handling logging in your application, you can use a simple config:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)  # log to console
+logging.basicConfig(level=logging.INFO, filename='podpac.log')  # log to a file podpac.log
+```
+
+or a more complicated configuration which handles only podpac logs:
+
+```python
+# log only podpac logs
+log = logging.getLogger('podpac')
+log.setLevel(logging.DEBUG)
+
+# log only podpac logs in a file
+import logging
+from logging import FileHandler
+log = logging.getLogger('podpac')
+log.setLevel(logging.DEBUG)
+log.addHandler(FileHandler('podpac.log', 'w'))
+```
+
+We have created a convience method `create_logfile()` in the `podpac.utils` module to
+automatically create a log file for only podpac logs.
+
 ## Import Conventions / API Conventions
 
 ### Public API

doc/source/index.rst

@@ -57,3 +57,7 @@ The purpose of PODPAC is to facilitate
     developer/contributing
     developer/aws
     developer/docs
+
+Acknowledgments
+-----------------
+This material is based upon work supported by NASA under Contract No 80NSSC18C0061.