Merge branch 'develop' into file_selection

.travis.yml

@@ -2,13 +2,15 @@ language: python
 dist: xenial
 jobs:
   include:
-    - python: '3.6'
-      script: pytest --cov=pysatMadrigal/
     - name: '3.7 with flake8'
       python: '3.7'
-      script: pytest --flake8 --cov=pysatMadrigal/
+      script:
+          - flake8 . --count --select=E,F,W
+          - pytest --cov=pysatMadrigal/
     - python: '3.8'
       script: pytest --cov=pysatMadrigal/
+    - python: '3.9'
+      script: pytest --cov=pysatMadrigal/
 
 services: xvfb
 cache: pip

.zenodo.json

@@ -16,22 +16,22 @@
     "creators": [
       {
         "affiliation": "U.S. Naval Research Laboratory", 
-        "name": "Angeline G. Burrell",
+        "name": "Burrell, Angeline G.",
         "orcid": "0000-0001-8875-9326"
       }, 
       {
         "affiliation": "Goddard Space Flight Center",
-        "name": "Jeff Klenzing",
+        "name": "Klenzing, Jeff",
         "orcid": "0000-0001-8321-6074"
       }, 
       {
         "affiliation": "The University of Texas at Dallas", 
-        "name": "Russell Stoneback",
+        "name": "Stoneback, Russell",
         "orcid": "0000-0001-7216-4336"  
       }, 
       {
         "affiliation": "Predictive Science", 
-        "name": "Asher Pembroke"
+        "name": "Pembroke, Asher"
       }
     ]
 }

CHANGELOG.md

@@ -7,12 +7,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Deprecations
   - Restructed Instrument methods, moving `madrigal` to `general` and extracting
     local methods from the instrument modules to platform-specific method files
+  - Cycled testing support to cover Python 3.7-3.9
 - Enhancements
   - Added coords from pysat.utils
   - Added Vertical TEC Instrument
   - Added documentation
   - Added load routine for simple formatted data
   - Expanded feedback during data downloads
+  - Updated documentation configuration to improve maintainability
+  - Updated documentation style, displaying logo on sidebar in html format
+  - Changed zenodo author name format for better BibTeX compliance
+  - Updated README information
 - Bug Fix
   - Updated Madrigal methods to simplify compound data types and enable
     creation of netCDF4 files using `Instrument.to_netcdf4()`

README.md

@@ -1,6 +1,6 @@
 <div align="left">
         <img height="0" width="0px">
-        <img width="20%" src="/docs/figures/pysatMadrigal.png" alt="pysatMadrigal" title="pysatMadrigal"</img>
+        <img width="20%" src="https://raw.githubusercontent.com/pysat/pysatMadrigal/main/docs/figures/pysatMadrigal.png" alt="pysatMadrigal" title="pysatMadrigal"</img>
 </div>
 
 # pysatMadrigal
@@ -16,11 +16,28 @@ pysat ([pysat documentation](http://pysat.readthedocs.io/en/latest/)).
 
 # Installation
 
-pysatMadrigal may be installed through pip or by cloning the git repository
+The following instructions provide a guide for installing pysatSpaceWeather and
+give some examples on how to use the routines.
+
+## Prerequisites
+
+pysatMadrigal uses common Python modules, as well as modules developed by and
+for the Space Physics community.  This module officially supports Python 3.7+.
+
+| Common modules | Community modules |
+| -------------- | ----------------- |
+| h5py           | madrigalWeb       |
+| numpy          | pysat >= 3.0.0    |
+| pandas         |                   |
+| xarray         |                   |
+
+
+## PyPi Installation
 ```
 pip install pysatMadrigal
 ```
 
+## GitHub Installation
 ```
 git clone https://github.com/pysat/pysatMadrigal.git
 ```
@@ -35,29 +52,25 @@ python setup.py install
 
 Note: pre-0.1.0 version
 -----------------------
-pysatMadrigal is currently provided as an alpha pre-release.  Much of the API is
-being built off of the upcoming pysat 3.0.0 software in order to streamline the
-usage and test coverage.  This version of pysat is planned for release later
-this year.  Currently, you can access the develop version of this through
-github:
+pysatMadrigal is currently provided as an alpha pre-release.  Feedback and
+contributions are appreciated.
 
-```
-git clone https://github.com/pysat/pysat.git
-cd pysat
-git checkout develop-3
-python setup.py install
-```
-
-It should be noted that this is a working branch and is subject to change.
-
-# Using with pysat
+# Examples
 
 The instrument modules are portable and designed to be run like any pysat
 instrument.
 
 ```
 import pysat
 from pysatMadrigal.instruments import dmsp_ivm
-
 ivm = pysat.Instrument(inst_module=dmsp_ivm, tag='utd', inst_id='f15')
 ```
+
+Another way to use the instruments in an external repository is to register the
+instruments.  This only needs to be done the first time you load an instrument.
+Afterward, pysat will identify them using the `platform` and `name` keywords.
+
+```
+pysat.utils.registry.register('pysatMadrigal.instruments.dmsp_ivm')
+dst = pysat.Instrument('dmsp', 'ivm', tag='utd', inst_id='f15')
+```

docs/conf.py

@@ -16,6 +16,7 @@
 # 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 json
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
@@ -38,8 +39,7 @@
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
               'numpydoc',
-              'm2r2'
-]
+              'm2r2']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
@@ -54,18 +54,21 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'pysatMadrigal'
-copyright = u'2020, Angeline G Burrell, Jeffrey Klenzing, Russell Stoneback'
-author = u'Angeline G Burrell, Jeffrey Klenzing, Russell Stoneback, Asher Pembroke'
+project = 'pysatMadrigal'
+title = '{:s} Documentation'.format(project)
+zenodo = json.loads(open('../.zenodo.json').read())
+author = ', '.join([creator['name'] for creator in zenodo['creators']])
+description = ''.join(['Tools for accessing and analyzing data from the ',
+                       'Madrigal database'])
+copyright = ', '.join(['2021', author])
 
 # 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 = u'0.0.2'
-# The full version, including alpha/beta/rc tags.
-release = u'0.0.2-alpha'
+doc_dir = os.path.abspath(os.path.dirname(__file__))
+with open(os.path.join(doc_dir, "..", project, "version.txt"), "r") as fin:
+    version = fin.read().strip()
+release = '{:s}-alpha'.format(version)  # Include alpha/beta/rc tags.
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -85,84 +88,61 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = ["_themes", ]
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = os.path.join(os.path.abspath('.'), 'figures', 'pysatMadrigal.png')
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['.static']
-
+html_theme_options = {'logo_only': True}
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'pysatMadrigaldoc'
-
+htmlhelp_basename = '{:s}doc'.format(project)
 
 # -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
+#
+# The paper size ('letterpaper' or 'a4paper').
+# 'papersize': 'letterpaper',
+#
+# The font size ('10pt', '11pt' or '12pt').
+# 'pointsize': '10pt',
+#
+# Additional stuff for the LaTeX preamble.
+# 'preamble': '',
+#
+# Latex figure (float) alignment
+# 'figure_align': 'htbp',
+latex_elements = {}
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, 'pysatMadrigal.tex', u'pysatMadrigal Documentation',
-     u'Angeline G Burrell, Jeffrey Klenzing, and Russell Stoneback', 'manual'),
-]
-
+latex_documents = [(master_doc, '{:s}.tex'.format(project), title, author,
+                    'manual')]
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pysatMadrigal', u'pysatMadrigal Documentation',
-     [author], 1)
-]
-
+man_pages = [(master_doc, project, title, [author], 1)]
 
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, 'pysatMadrigal', u'pysatMadrigal Documentation',
-     author, 'pysatMadrigal',
-     'Tools for accessing and analyzing data from the Madrigal database',
-     'Space Physics'),
-]
-
-
+texinfo_documents = [(master_doc, project, title, author, project,
+                      description, 'Space Physics')]
 
 # -- Options for Epub output ----------------------------------------------
 
@@ -184,7 +164,5 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}

pysatMadrigal/instruments/methods/general.py

@@ -1,8 +1,7 @@
 # -*- coding: utf-8 -*-.
-"""Provides default routines for integrating CEDAR Madrigal instruments into
-pysat, reducing the amount of user intervention.
+"""General routines for integrating CEDAR Madrigal instruments into pysat.
 
- """
+"""
 
 import datetime as dt
 import gzip
@@ -22,36 +21,33 @@
 
 
 def cedar_rules():
-    """ General acknowledgement statement for Madrigal data.
+    """General acknowledgement statement for Madrigal data.
 
     Returns
     -------
-    ackn : string
+    ackn : str
         String with general acknowledgement for all CEDAR Madrigal data
 
     """
-    ackn = "Contact the PI when using this data, in accordance with the CEDAR"
-    ackn += " 'Rules of the Road'"
+    ackn = "".join(["Contact the PI when using this data, in accordance ",
+                    "with the CEDAR 'Rules of the Road'"])
     return ackn
 
 
 def load(fnames, tag=None, inst_id=None, xarray_coords=None):
     """Loads data from Madrigal into Pandas or XArray
 
-    This routine is called as needed by pysat. It is not intended
-    for direct user interaction.
-
     Parameters
     ----------
     fnames : array-like
         iterable of filename strings, full path, to data files to be loaded.
         This input is nominally provided by pysat itself.
-    tag : string
+    tag : str
         tag name used to identify particular data set to be loaded.
         This input is nominally provided by pysat itself. While
         tag defaults to None here, pysat provides '' as the default
         tag unless specified by user at Instrument instantiation. (default='')
-    inst_id : string
+    inst_id : str
         Satellite ID used to identify particular data set to be loaded.
         This input is nominally provided by pysat itself. (default='')
     xarray_coords : list or NoneType
@@ -67,15 +63,17 @@ def load(fnames, tag=None, inst_id=None, xarray_coords=None):
     Returns
     -------
     data : pds.DataFrame or xr.Dataset
-        A pandas DataFrame or xarray Dataset holding the data from the HDF5
-        file
+        A pandas DataFrame or xarray Dataset holding the data from the file
     meta : pysat.Meta
-        Metadata from the HDF5 file, as well as default values from pysat
+        Metadata from the file, as well as default values from pysat
 
     Note
     ----
     Currently HDF5 reading breaks if a different file type was used previously
 
+    This routine is called as needed by pysat. It is not intended
+    for direct user interaction.
+
     """
     # Test the file formats
     load_file_types = {ftype: [] for ftype in file_types.keys()}