Merge 5896dd0 into 66ea94a

pysat · Apr 27, 2021 · c414868 · c414868
2 parents 66ea94a + 5896dd0
commit c414868
Show file tree

Hide file tree

Showing 26 changed files with 705 additions and 34 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,42 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Documentation Check
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [3.9]
+
+    name:
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r test_requirements.txt
+        pip install -r requirements.txt
+
+    - name: Set up pysat
+      run: |
+        mkdir pysatData
+        python -c "import pysat; pysat.params['data_dirs'] = './pysatData'"
+
+    - name: Check documentation build
+      run: sphinx-build -E -b html docs dist/docs
+
+    - name: Check documentation links
+      run: sphinx-build -b linkcheck docs dist/docs
+
+    - name: Load .zenodo.json to check for errors
+      run: python -c "import json; json.loads(open('.zenodo.json').read())"
diff --git a/.zenodo.json b/.zenodo.json
@@ -6,26 +6,27 @@
         "orcid": "0000-0001-8321-6074"
       },
       {
-        "affiliation": "University of Texas at Dallas",
+        "affiliation": "The University of Texas at Dallas",
         "name": "Russell Stoneback",
         "orcid": "0000-0001-7216-4336"
       },
+      {
+        "affiliation": "Catholic University of America, Goddard Space Flight Center",
+        "name": "Jonathon Smith",
+        "orcid": "0000-0002-8191-4765"
+      },
       {
         "affiliation": "U.S. Naval Research Laboratory",
-        "name": "Angeline Burrell",
+        "name": "Angeline G. Burrell",
         "orcid": "0000-0001-8875-9326"
       },
       {
+        "affiliation": "Predictive Science",
         "name": "Asher Pembroke"
       },
       {
         "name": "Carey Spence",
         "orcid": "0000-0001-8340-5625"
       }
-    ],
-    "access_right": "open",
-    "resource_type": {
-      "type": "software",
-      "title": "Software"
-    }
+    ]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,9 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [next version] - 2020-09-14
+## [0.1.0] - 2021-01-26
 - Updated Instruments and routines to conform with changes made for pysat 3.0
+- Added documentation
 - New Instruments
   - GOLD Nmax
 - Use GitHub Actions as primary CI test environment

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@ Contributing
 ============
 
 Bug reports, feature suggestions and other contributions are greatly
-appreciated!  Pysat is a community-driven project and welcomes both feedback and
+appreciated!  pysat is a community-driven project and welcomes both feedback and
 contributions.
 
 Short version
@@ -48,14 +48,17 @@ To set up `pysatNASA` for local development:
 
     git checkout -b name-of-your-bugfix-or-feature
 
-   Now you can make your changes locally. Tests for new instruments are
-   performed automatically.  Tests for custom functions should be added to the
-   appropriately named file in ``pysatNASA/tests``.  For example, custom functions
-   for the OMNI HRO data are tested in ``pysatNASA/tests/test_omni_hro.py``.  If
-   no test file exists, then you should create one.  This testing uses pytest,
-   which will run tests on any python file in the test directory that starts
-   with ``test``.  Classes must begin with ``Test``, and methods must begin
-   with ``test`` as well.
+   Now you can make your changes locally.
+
+   Tests for new instruments are performed automatically.  See discussion
+   `here <https://pysat.readthedocs.io/en/develop-3/new_instrument.html#testing-support>`_
+   for more information on triggering these standard tests.
+
+   Tests for custom functions should be added to the appropriately named file
+   in ``pysatNASA/tests``.  For example, custom functions for the OMNI HRO data
+   are tested in ``pysatNASA/tests/test_omni_hro.py``.  If no test file exists,
+   then you should create one.  This testing uses pytest, which will run tests on any python file in the test directory that starts with ``test``.  Classes must begin with ``Test``, and methods must begin with ``test`` as well.
+
 
 4. When you're done making changes, run all the checks to ensure that nothing
    is broken on your local system, as well as check for flake8 compliance::
@@ -85,11 +88,45 @@ For merging, you should:
 
 1. Include an example for use
 2. Add a note to ``CHANGELOG.md`` about the changes
-3. Ensure that all checks passed (current checks include Travis-CI (pytest and flake8)
-   and Coveralls) [1]_
+3. Update the author list in ``zenodo.json`` if applicable
+4. Ensure that all checks passed (current checks include Travis-CI (pytest and
+   flake8) and Coveralls) [1]_
 
 .. [1] If you don't have all the necessary Python versions available locally or
-       have trouble building all the testing environments, you can rely on
-       Travis to run the tests for each change you add in the pull request.
-       Because testing here will delay tests by other developers, please ensure
-       that the code passes all tests on your local system first.
+      have trouble building all the testing environments, you can rely on
+      Travis to run the tests for each change you add in the pull request.
+      Because testing here will delay tests by other developers, please ensure
+      that the code passes all tests on your local system first.
+
+ Project Style Guidelines
+ ------------------------
+
+ In general, pysat follows PEP8 and numpydoc guidelines.  Pytest runs the unit
+ and integration tests, flake8 checks for style, and sphinx-build performs
+ documentation tests.  However, there are certain additional style elements that
+ have been adopted to ensure the project maintains a consistent coding style.
+ These include:
+
+ * Line breaks should occur before a binary operator (ignoring flake8 W503)
+ * Combine long strings using `join`
+ * Preferably break long lines on open parentheses rather than using `\`
+ * Use no more than 80 characters per line
+ * Avoid using Instrument class key attribute names as unrelated variable names:
+   `platform`, `name`, `tag`, and `inst_id`
+ * The pysat logger is imported into each sub-module and provides status updates
+   at the info and warning levels (as appropriate)
+ * Several dependent packages have common nicknames, including::
+   * `import datetime as dt`
+   * `import numpy as np`
+   * `import pandas as pds`
+   * `import xarray as xr`
+ * All classes should have `__repr__` and `__str__` functions
+ * Docstrings use `Note` instead of `Notes`
+ * Try to avoid creating a try/except statement where except passes
+ * Use setup and teardown in test classes
+ * Use pytest parametrize in test classes when appropriate
+ * Provide testing class methods with informative failure statements and
+   descriptive, one-line docstrings
+ * Block and inline comments should use proper English grammar and punctuation
+   with the exception of single sentences in a block, which may then omit the
+   final period
diff --git a/README.md b/README.md
@@ -1,10 +1,34 @@
 # pysatNASA: pysat support for NASA instruments
+[![PyPI Package latest release](https://img.shields.io/pypi/v/pysatNASA.svg)](https://pypi.python.org/pypi/pysatNASA)
 [![Build Status](https://github.com/github/docs/actions/workflows/main.yml/badge.svg)](https://github.com/github/docs/actions/workflows/main.yml/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/pysat/pysatNASA/badge.svg?branch=main)](https://coveralls.io/github/pysat/pysatNASA?branch=main)
+
+[![Documentation Status](https://readthedocs.org/projects/pysatnasa/badge/?version=latest)](https://pysatnasa.readthedocs.io/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/287387638.svg)](https://zenodo.org/badge/latestdoi/287387638)
 
 # Installation
 
+The following instructions provide a guide for installing pysatSpaceWeather and give
+some examples on how to use the routines
+
+### Prerequisites
+
+pysatSpaceWeather 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 |
+| -------------- | ----------------- |
+| beautifulsoup4 | cdflib            |
+| lxml           | pysat             |
+| netCDF4        |                   |
+| numpy          |                   |
+| pandas         |                   |
+| requests       |                   |
+| xarray         |                   |
+
+## GitHub Installation
+
 Currently, the main way to get pysatNASA is through github.
 
 ```
@@ -21,14 +45,7 @@ python setup.py install
 
 Note: pre-1.0.0 version
 ------------------
-pysatNASA is currently in an initial development phase.  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:
-```
-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.
+pysatNASA is currently in an initial development phase and requires pysat 3.0.0.  
 
 # Using with pysat
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = pysatNASA
+SOURCEDIR     = .
+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)
diff --git a/docs/citing.rst b/docs/citing.rst
@@ -0,0 +1,32 @@
+Citation Guidelines
+===================
+
+When publishing work that uses pysatNASA, please cite the package and
+any package it depends on that plays an important role in your analysis.
+Specifying which version of pysatNASA used will also improve the
+reproducibility of your presented results.
+
+pysatNASA
+---------
+
+* Klenzing, J., et al. (2020).
+  pysat/pysatNASA: Initial Release (Version 0.0.1). Zenodo.
+  doi:10.5281/zenodo.3986132
+
+.. code-block:: latex
+
+  @software{pysatNASA,
+    author       = {Klenzing, J. and
+                    Stoneback, R.A. and
+                    Burrell, A.G. and
+                    Pembroke, A. and
+                    Depew, M. and
+                    Spence, C.},
+    title        = {pysat/pysatNASA: Initial Release},
+    month        = aug,
+    year         = 2020,
+    publisher    = {Zenodo},
+    version      = {v0.0.1},
+    doi          = {10.5281/zenodo.3986132},
+    url          = {https://doi.org/10.5281/zenodo.3986132}
+  }